#internal/page

#internal/page

Package page builds the chrome a converted Markdown body is wrapped in.

The body HTML itself comes from the html package; everything a reader sees around it is built here: the sidebar and its navigation tree, the topbar, the table of contents, the breadcrumbs, the version and locale pickers, the superseded-version notice, the share control, the page footer, the search surface, the Pagefind filter and metadata elements, and every SEO tag in the head including the JSON-LD documents.

GenerateHTML is the entry point the build calls once per locale-and-version pass. It converts every page of one mount, collects the terms the pages declared, synthesizes the glossary page from them, and wraps each page in the full document -- returning a map keyed by each page's output key, so no caller has to staple the mount prefix on afterwards.

#Ordered inputs

The Python surface this replaces passed insertion-ordered dicts of Markdown sources, and three decisions read that order: which nav group title wins when two pages in one directory declare different ones, how two groups whose titles sort equal are ordered, and the order pages are converted in. A Go map has no order, so the sources arrive as a slice of SourceFile and the order is the caller's to state.

#JSON-LD is emitted in Python's spelling

The structured data is written with the separators and the key order Python's json.dumps produces -- ", " between items, ": " between a key and its value, and properties in the order the emitter built them. That is why identity.Entity is an ordered property list and why util.PythonJSON, which sorts keys and writes no spaces, is not what emits these documents.

#PagefindWidgetBundle

const PagefindWidgetBundle = "pagefind/pagefind-ui.js"

PagefindWidgetBundle is the widget bundle a page names when it loads Pagefind's own search UI. A tree in which no page names it is a tree the widget can be pruned from.

#DocumentTitleLimit

const DocumentTitleLimit = 60

DocumentTitleLimit is the longest a document title should be: a search engine displays about 50 to 60 characters of one and cuts the rest, and the check that measures a page's title holds every page to that number.

#PagefindFacetKeys

var PagefindFacetKeys = []string{

PagefindFacetKeys are the facets the corpus carries, in the order they are emitted. Every one is a Pagefind filter, so every one is selectable in the search UI; "tags" is last because it is the only multi-valued key.

The slice is package state a caller must not write to.

#PagefindUIAssets

var PagefindUIAssets = []string{

PagefindUIAssets is every file the Pagefind indexer writes that belongs to its own search WIDGET rather than to the index or the query API.

A framework theme draws its own search surface, so these are neither loaded nor kept: they would be a payload every deploy carries and no page references, and their stylesheets paint rounded corners the framework does not allow.

The slice is package state a caller must not write to.

#PageDates

type PageDates struct

PageDates are the dates one page states: when it was first published and when it was last changed, each in ISO form and each "" when unstated.

#Options

type Options struct

Options is everything one locale-and-version pass of the build hands the page renderer.

It mirrors the keyword arguments of the Python function it replaces, with two omissions: that function also took the current version and an is-latest flag, and read neither.

Start from NewOptions rather than from the zero value. Four settings default to true or to a non-empty string in the surface this replaces -- the previous/next links, the reading-progress line, the glossary page and the code-icon style -- so a zero-valued Options turns three features off and asks for a code-icon style that does not exist.

#NotFoundOptions

type NotFoundOptions struct

NotFoundOptions is what the 404 page is built from.

It mirrors the keyword arguments of the Python function it replaces, with one omission: that function also took the repository URL and never passed it on, because the 404 has no source file to offer an edit link for.

#SourceFile

type SourceFile struct

SourceFile is one Markdown source and the docs-relative path it was read from.

It stands in for one entry of the insertion-ordered dict the Python surface passed around: the order of the slice is the order the pages were walked, and three navigation decisions read it (see the package documentation).

#NavItem

type NavItem struct

NavItem is one entry of the sidebar navigation tree.

An entry is either a page or a group, and Group is what tells them apart: a page carries Label, Path and MdPath, while a group carries Group, Slug and Items. Nothing carries both.

#VersionEntry

type VersionEntry struct

VersionEntry is one version the project has published, as the config declares it. The order of the configured list is oldest to newest: the version picker reads the last entry as the current one.

#LocaleEntry

type LocaleEntry struct

LocaleEntry is one locale the project publishes, as the config declares it.

#PagefindFacets

type PagefindFacets struct

PagefindFacets are the facet values one page emits for the search index.

#SEOOptions

type SEOOptions struct

SEOOptions is everything the head's SEO block is built from.

It mirrors the keyword arguments of the Python function it replaces, one field per argument, with one omission: that function also took the current locale and never read it.

#WrapOptions

type WrapOptions struct

WrapOptions is everything one page's document is built from.

It mirrors the keyword arguments of the Python function it replaces, with two omissions: that function also took the current version and an is-latest flag, and read neither.

Three fields are pointers because the empty string is a legal value for them and "not stated" is a different answer: a page at its mount root really does have an empty hop. Leaving one nil takes the default the field documents.

#DocumentTitleParts

type DocumentTitleParts struct

DocumentTitleParts are the written values a page's