Documentation
¶
Index ¶
- Constants
- func BuildSearchDocuments(pages []Page) []docfind.Document
- func BuildSearchDocumentsBase(pages []Page, base string) []docfind.Document
- func ExtractFrontmatter(src string) map[string]any
- func InjectHeadingAnchors(html string) string
- func LocaleURL(locale, defaultLocale, path string) string
- func NormalizePagePath(path string) string
- func PageURL(path string) string
- func ParseKeywords(raw string) []string
- func PathToTitle(path string) string
- func SortPages(pages []Page)
- func StripFrontmatter(src string) string
- func StripHTMLTags(s string) string
- type Badge
- type Breadcrumb
- type Config
- type Frontmatter
- type HeadTag
- type HeroAction
- type HeroConfig
- type NavOverride
- type Page
- type SearchEntry
- type SidebarItem
- type SidebarNavConfig
- type TOCItem
- type TocConfig
Constants ¶
const DocsBasePath = "/docs"
DocsBasePath is the URL prefix the docs plugin mounts pages under. It is the single source of truth for absolute docs URLs (sidebar, prev/next links, and breadcrumbs) so they agree.
Variables ¶
This section is empty.
Functions ¶
func BuildSearchDocuments ¶ added in v0.4.0
BuildSearchDocuments converts docs pages into docfind index documents. Tags and categories are merged into the WASM index keywords so searches against the tags/categories surface the page; the JSON fallback index gets the same terms appended to content (see BuildSearchIndex).
func BuildSearchDocumentsBase ¶
BuildSearchDocumentsBase is BuildSearchDocuments with a base path prefix.
func ExtractFrontmatter ¶
ExtractFrontmatter parses YAML frontmatter from markdown content. The returned map uses the shared mini-YAML parser (internal/frontmatter) so nested keys, typed values, and flow collections are supported.
func InjectHeadingAnchors ¶
InjectHeadingAnchors post-processes rendered HTML to add anchor link buttons to headings that have id attributes.
func LocaleURL ¶ added in v0.4.0
LocaleURL returns the absolute URL for a docs page in a locale. The default locale is unprefixed (/docs/...); other locales are path-prefixed (/fr/docs/...).
func NormalizePagePath ¶
NormalizePagePath strips trailing "/index" from a page path for URL generation. "index" -> "" "guides/index" -> "guides" "guides/advanced" -> "guides/advanced"
func ParseKeywords ¶
ParseKeywords splits a frontmatter `keywords:` value (comma or space separated) into a slice of trimmed keywords.
func PathToTitle ¶
PathToTitle converts a file path or directory name to a human-readable title.
func SortPages ¶
func SortPages(pages []Page)
SortPages sorts pages by directory, then order, then title. A per-item `sidebar: {order}` override wins over the top-level `order:` frontmatter.
func StripFrontmatter ¶
StripFrontmatter removes YAML frontmatter from markdown content.
func StripHTMLTags ¶
StripHTMLTags removes HTML tags from a string, keeping the document's line structure: block-level tags (p, li, headings, table cells, ...) become line breaks, and intra-line whitespace is collapsed. This keeps extracted text readable (paragraphs stay separate) and prevents adjacent blocks from running together, e.g. "<td>File</td><td>When loaded</td>" -> "File\nWhen loaded".
Types ¶
type Badge ¶ added in v0.4.0
Badge is a small colored chip rendered next to a sidebar link or page heading.
type Breadcrumb ¶
type Breadcrumb struct {
Label string `json:"label"` // display label
URL string `json:"url"` // URL (empty for current page)
IsLast bool `json:"isLast"` // true if this is the current page
}
Breadcrumb represents a single breadcrumb item.
func BuildBreadcrumbs ¶
func BuildBreadcrumbs(path string) []Breadcrumb
BuildBreadcrumbs returns the breadcrumb trail as a slice. Index pages (e.g. "guides/index") produce breadcrumbs ending at the directory name ("Guides") - no "Index" crumb.
func BuildBreadcrumbsTitled ¶
func BuildBreadcrumbsTitled(locale, defaultLocale, path string, pages []Page) []Breadcrumb
BuildBreadcrumbsTitled is BuildBreadcrumbsURL with real page titles: a crumb whose path matches a page (keyed by NormalizePagePath) uses that page's title instead of the humanised file name.
func BuildBreadcrumbsURL ¶ added in v0.4.0
func BuildBreadcrumbsURL(locale, defaultLocale, path string) []Breadcrumb
BuildBreadcrumbsURL is BuildBreadcrumbs with a locale prefix applied to every non-default locale's crumb URLs.
type Config ¶
type Config struct {
ContentDir string // relative to project root
Root string // absolute project root
MDConfig markdown.Config // markdown rendering config
// GitLastUpdated fills Page.Updated from the file's last git commit when
// frontmatter does not set it.
GitLastUpdated bool
}
Config holds configuration for scanning documentation.
type Frontmatter ¶ added in v0.4.0
type Frontmatter struct {
Title string
Order int
Sidebar string
CustomSidebar []SidebarItem
SidebarConfig *SidebarNavConfig
Badge *Badge
Keywords []string
Description string
Toc TocConfig
Hero *HeroConfig
Template string
Head []HeadTag
Prev *NavOverride
Next *NavOverride
Draft bool
EditURL string
Tags []string
Categories []string
Date string
Updated string
}
Frontmatter is the fully decoded YAML frontmatter for a documentation page.
func ParseMD ¶
func ParseMD(src string, cfg markdown.Config) (html string, fm *Frontmatter)
ParseMD parses a .md file, extracting frontmatter and rendering markdown.
func ParseMDX ¶
func ParseMDX(src string, cfg markdown.Config) (html string, fm *Frontmatter)
ParseMDX parses an .mdx file, extracting frontmatter and rendering it with MDX semantics (ESM, JSX and expressions). The HTML is the static form used for search and TOC extraction: components are dropped, code is highlighted.
type HeroAction ¶ added in v0.4.0
type HeroAction struct {
Text string `json:"text"`
Link string `json:"link"`
Variant string `json:"variant,omitempty"`
}
HeroAction is a button rendered inside the hero block.
type HeroConfig ¶ added in v0.4.0
type HeroConfig struct {
Title string `json:"title"`
Tagline string `json:"tagline"`
Image string `json:"image,omitempty"`
Actions []HeroAction `json:"actions,omitempty"`
}
HeroConfig is the hero block rendered by template:hero layouts.
type NavOverride ¶ added in v0.4.0
type NavOverride struct {
}
NavOverride overrides the auto-computed previous/next page link.
type Page ¶
type Page struct {
Path string `json:"path"`
Title string `json:"title"`
Order int `json:"order"`
Content string `json:"content"`
Dir string `json:"dir"`
Sidebar string `json:"sidebar"`
SourcePath string `json:"sourcePath"`
Keywords []string `json:"keywords,omitempty"`
CustomSidebar []SidebarItem `json:"customSidebar"`
// Phase 1 - content fields
Description string `json:"description,omitempty"`
Toc TocConfig `json:"-"`
Hero *HeroConfig `json:"-"`
Template string `json:"template,omitempty"`
Head []HeadTag `json:"-"`
Prev *NavOverride `json:"-"`
Next *NavOverride `json:"-"`
// Phase 2 - navigation surface
SidebarCfg *SidebarNavConfig `json:"-"`
Badge *Badge `json:"badge,omitempty"`
// Phase 3 - workflow
Draft bool `json:"draft,omitempty"`
EditURL string `json:"editUrl,omitempty"`
// Phase 4 - search/org
Tags []string `json:"tags,omitempty"`
Categories []string `json:"categories,omitempty"`
// Phase 5 - dates (RFC3339 or YYYY-MM-DD strings). Date is the published
// date; Updated is the last-modified date (frontmatter, else git).
Date string `json:"date,omitempty"`
Updated string `json:"updated,omitempty"`
// Authors lists recent contributors to the source file (from git), most
// recent first. Populated when Config.GitLastUpdated is set.
Authors []string `json:"authors,omitempty"`
// Phase 6 - i18n/versioning. Locale is the page's locale ("" when i18n is
// not configured); Version is its docs version ("" when unversioned); URL is
// the page's absolute site URL, set by the docs plugin (locale/version
// aware).
Locale string `json:"locale,omitempty"`
Version string `json:"version,omitempty"`
URL string `json:"url,omitempty"`
}
Page represents a single documentation page.
type SearchEntry ¶
type SearchEntry struct {
Title string `json:"title"`
Path string `json:"path"`
Content string `json:"content"`
Tags []string `json:"tags,omitempty"`
Categories []string `json:"categories,omitempty"`
}
SearchEntry represents a search index entry.
func BuildSearchIndex ¶
func BuildSearchIndex(pages []Page) []SearchEntry
BuildSearchIndex generates a search index from documentation pages.
func BuildSearchIndexBase ¶
func BuildSearchIndexBase(pages []Page, base string) []SearchEntry
BuildSearchIndexBase is BuildSearchIndex with a site base path prefixed onto every entry. Entries use each page's own (locale- and version-aware) URL, so a section index is /docs/guides/, never /docs/guides/index/.
type SidebarItem ¶
type SidebarItem struct {
Title string `json:"title"`
URL string `json:"url"`
Active bool `json:"active"`
Children []SidebarItem `json:"children,omitempty"`
IndexURL string `json:"indexURL,omitempty"`
Collapsible bool `json:"collapsible,omitempty"`
Expanded bool `json:"expanded,omitempty"`
Icon string `json:"icon,omitempty"`
Badge *Badge `json:"badge,omitempty"`
}
SidebarItem represents a single entry in a recursive sidebar tree. Items with Children act as expandable folder sections. Items with URL (and no Children) act as clickable links. Items with neither are plain text headers.
func BuildSidebarTree ¶
func BuildSidebarTree(pages []Page) []SidebarItem
BuildSidebarTree builds a recursive sidebar tree from pages. Pages are grouped by their directory structure - each subdirectory becomes a nested SidebarItem with Children, supporting infinite nesting. Frontmatter navigation metadata (`sidebar: {...}` and top-level `badge`) is applied here: `hidden` pages are dropped from the nav (still renderable and searchable), `label` overrides the displayed title, `order` overrides the sort position, and `badge` / `icon` decorate the entry. Directory sections inherit `collapsible` / `defaultOpen` / `badge` / `icon` from their index page.
func EnrichSidebarItems ¶
func EnrichSidebarItems(items []SidebarItem, currentPath string) []SidebarItem
EnrichSidebarItems pre-computes IndexURL, Collapsible, and Expanded fields for each sidebar item relative to the given currentPath. This allows the TSX renderer to use these values directly without function calls. Values already set by frontmatter (sidebar: {collapsible, defaultOpen}) are preserved and OR'd with the auto-derived values.
func EnrichSidebarItemsURL ¶ added in v0.4.0
func EnrichSidebarItemsURL(items []SidebarItem, activeURL string) []SidebarItem
EnrichSidebarItemsURL is EnrichSidebarItems keyed by the current page's full (locale/version-aware) URL, so active/expanded state is correct under i18n and versioning.
type SidebarNavConfig ¶ added in v0.4.0
type SidebarNavConfig struct {
}
SidebarNavConfig carries per-page navigation metadata that overrides the sidebar tree entry for this page (label, order, hidden, badge, etc.).
type TOCItem ¶
type TOCItem struct {
Title string `json:"title"` // displayed text
ID string `json:"id"` // anchor id
Depth int `json:"depth"` // 2 for h2, 3 for h3
}
TOCItem represents a single heading entry in the table of contents.
func ExtractTOC ¶
ExtractTOC parses rendered HTML and extracts the default heading range (h2-h3) for the TOC sidebar.
func ExtractTOCLevels ¶ added in v0.4.0
ExtractTOCLevels parses rendered HTML and extracts headings with levels in the inclusive [minLevel, maxLevel] range (2-6). Levels outside 1-6 and an empty range are clamped to the defaults (2-3).