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.
#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.
#ResolveMarkdown
func ResolveMarkdown(content string, resolve directives.Resolver, validNames directives.NameSet) (Doc, error)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.
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.