Documentation
¶
Overview ¶
Package docs holds the shared rendering helpers the docs generators (cmd/magus-docs, cmd/magus-spelldocs) use to emit the committed Markdown under docs/**. Keeping the frontmatter block in one place means both generators emit the same YAML the site's parser expects, so a fix here (quoting rules, key order) lands in every generated page at once.
Index ¶
Constants ¶
const RepoBlob = "https://github.com/egladman/magus/blob/main"
RepoBlob is the GitHub source base for the docs' inline source links. It is pinned to the default branch rather than a commit hash on purpose: the committed docs embed these links, so a raw HEAD hash would rewrite on every commit and trip the `generate` drift gate. It mirrors the constant in cmd/magus-docs; when a release tag exists this can point at it.
Variables ¶
This section is empty.
Functions ¶
func RepoRoot ¶
func RepoRoot() string
RepoRoot walks up from the working directory to the directory holding go.mod (the module root), so source paths resolve whether a generator runs from the repo root (go run) or a package directory (go test). Falls back to "." if none is found.
func SourceURL ¶
SourceURL builds a RepoBlob link to the first line of repoRoot/path whose text contains match, so a link points at the code that handles something (a type, a binding, an option parse site). The line is resolved from the working tree so it stays correct if the code moves; on any read miss or no match it links to the file without a line anchor.
func StripFrontmatter ¶ added in v0.4.0
StripFrontmatter returns content with any leading frontmatter block removed, so a caller parsing the markdown body (heading extraction, rendering) never sees the YAML header - and never mistakes the header's closing "---" for a setext-heading underline of the line above it. Content with no valid block is returned unchanged. It shares ParseFrontmatter's fence detection so the two agree on where the body begins.
func WriteFrontmatter ¶
func WriteFrontmatter(b *strings.Builder, f Frontmatter)
WriteFrontmatter emits the site's YAML frontmatter block. Values containing a colon, quote, or edge whitespace are quoted so a YAML parser can't misread them. A page with no page_type/aliases leaves those fields zero.
Types ¶
type Frontmatter ¶
type Frontmatter struct {
Title string `yaml:"title"`
PageType string `yaml:"page_type"` // "overview" for hub/index pages; "" otherwise
// GeneratedFrom names what this page was generated from, so the site can tell a
// generated page from a hand-written one without guessing from its path, and can
// point "Suggest an edit" at the real source instead of the generated .md. Either
// a repo-relative path/glob ("internal/config/config.go", one or more comma-joined
// globs) or an in-site section path ending in "/" ("reference/api/") for a page
// whose true source has no single file - the renderer tells the two apart by that
// trailing slash. "" for a hand-written page.
GeneratedFrom string `yaml:"generated_from"`
Aliases []string `yaml:"aliases"` // old clean URLs that should redirect here (parity on a move)
Description string `yaml:"description"`
Tags []string `yaml:"tags"`
}
Frontmatter is the frontmatter a generated docs page carries. Title and Tags are always emitted; PageType, GeneratedFrom, and Aliases only when set. Key order is fixed (title, page_type, generated_from, aliases, description, tags) so regenerated output stays byte-stable. The yaml tags let ParseFrontmatter read back a block WriteFrontmatter emitted.
func ParseFrontmatter ¶ added in v0.2.0
func ParseFrontmatter(content string) (Frontmatter, bool)
ParseFrontmatter reads a leading YAML frontmatter block (a "---" line, the YAML body, then a closing "---" line) off a markdown document, returning the parsed fields and ok=true. A document with no leading block, or one whose YAML does not parse, yields a zero Frontmatter and ok=false - callers treat frontmatter as best-effort metadata, never a hard error. The two failure modes (no block present vs. a present-but-malformed block) deliberately collapse to the same ok=false: the sole caller wants the fields or nothing, and cares about neither reason. It is the read counterpart to WriteFrontmatter, kept here so both halves of the format live together.
Source Files