On this page
The shared resolution pipeline the build, the check and gen all start from: walk the docs directory, parse each page's frontmatter, resolve its directives.
#internal/docs
#internal/docs
Package docs is the shared resolution pipeline for a project's docs/ templates: it walks the docs directory, parses each page's frontmatter, and resolves every directive the page carries.
The build, the check and gen all start from the same walk, so the answer to "what pages does this project have, and what do they say once their directives are resolved?" has one definition rather than three.
#One resolved-document type
Doc is that one type. The packages downstream of the walk each read a narrower slice of a page -- the manifest wants the frontmatter, the resolved text and the raw template; the staleness store wants the frontmatter and the raw template -- and each declares its own struct for that slice so it does not depend on this package. The conversions live here, so a caller hands the walk's result to either of them without restating the mapping.
#Doc
type Doc structDoc is one docs-tree page, parsed and resolved.
Frontmatter is the page's parsed metadata block, empty when the page carries none. Resolved is the body with every directive replaced by what answered it. Raw is the same body BEFORE resolution, which is what the content hash covers -- so a directive whose output moved does not read as a page edit. FrontmatterLines is how many source lines the frontmatter occupied, which is what maps a body line number back to its line in the file; it is zero when there is no frontmatter.
#CollisionError
type CollisionError structCollisionError is two pages, one handwritten and one generated, claiming the same address.
The two docs roots merge into one URL namespace, so a page's path relative to its own root is its address. Two files that produce one address would make the published page depend on which root was walked first; this is the refusal instead, and it names both files.
#ManifestDocs
func ManifestDocs(all map[string]Doc) map[string]manifest.DocManifestDocs converts a whole walk result for the manifest writer, keeping every key as it stands.
#StalenessDocs
func StalenessDocs(all map[string]Doc) map[string]staleness.DocStalenessDocs converts a whole walk result for the hash store, keeping every key as it stands.
The store keys a page by its docs-relative path prefixed with its locale when the project declares more than one, so a caller that prefixes does so after this call.
#ValidNames
func ValidNames(config map[string]any) (directives.NameSet, error)ValidNames is the set of directive names this project may use: every built-in plus every name the config's "directives" key declares.
A custom name that does not match the directive-name grammar is a DirectiveError. The declared names are checked in sorted order, so a config with two malformed names always names the same one -- the Python iterated a set and named whichever the hash order put first.
#Roots
func Roots(config map[string]any, docsDir, baseDir string) []stringRoots returns the directories a project's pages come from, in the order [ResolveAll] walks them: the handwritten root the config names, then the generated root selfdoc writes its own pages into.
docsDir names the handwritten root; pass "" to take it from the config's "docs" key, resolved against baseDir. baseDir is the project root every relative path in the config resolves against.
Every caller that has to find a page by its docs-relative path asks here, so the two-root namespace is declared once rather than re-derived.
#FindPage
func FindPage(config map[string]any, docsDir, baseDir, relPath string) (string, bool)FindPage returns the path of the page at relPath -- a docs-relative path with forward slashes -- looked up across the roots [Roots] reports, and reports whether one of them holds it.
A page keeps its address wherever it is authored, so a caller that reads a page off disk must look in both roots or it will report a generated page missing.
#ResolveMarkdown
func ResolveMarkdown(ResolveMarkdown parses and resolves one Markdown source into a Doc.
Every page in a walk result goes through here, whether it came off disk or out of an overlay, and so does any caller that has to resolve a page the walk never sees.
#ResolveAll
func ResolveAll(ResolveAll walks a project's docs directory and resolves every .md template in it, keyed by each page's path relative to the docs directory with forward slashes.
docsDir names the directory to walk; pass "" to take it from the config's "docs" key, resolved against baseDir. baseDir is the project root every relative path in the config resolves against.
overlay maps a docs-relative path to Markdown source held in memory. Each entry is parsed and resolved exactly like a file on disk and then replaces (or adds to) the walked result, so a caller can render content that was never written -- an editor buffer, or the post pages the build would otherwise inject into the docs tree.
Two kinds of file in the tree are not pages: the build output directory, which would otherwise feed a previous build's artifacts back in, and an underscore-prefixed template, which is a partial included by a page rather than a page of its own.
#Two roots, one namespace
A project's pages come from two directories: the handwritten one the config names, and the generated one selfdoc writes beside the rest of its generated state. A page's key is its path relative to whichever root it came from, so the two roots merge into one namespace and a page keeps its address wherever it is authored. Two pages that would take the same address are a [CollisionError] naming both files, never a silent win for one of them.
Directories and files are read in sorted order. The Python walked in directory-listing order, which is arbitrary, and its callers sort where they need determinism; the only thing the order decides here is which of two unresolvable pages reports its error first.
#Doc.ManifestDoc
func (d Doc) ManifestDoc() manifest.DocManifestDoc narrows d to the slice the manifest writer reads.
#Doc.StalenessDoc
func (d Doc) StalenessDoc() staleness.DocStalenessDoc narrows d to the slice the hash store reads.
#CollisionError.Error
func (e *CollisionError) Error() string