docs

package
v0.4.0-rc.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
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

func BuildSearchDocuments(pages []Page) []docfind.Document

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 ExtractFrontmatter

func ExtractFrontmatter(src string) map[string]any

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

func InjectHeadingAnchors(html string) string

InjectHeadingAnchors post-processes rendered HTML to add anchor link buttons to headings that have id attributes.

func LocaleURL added in v0.4.0

func LocaleURL(locale, defaultLocale, path string) string

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

func NormalizePagePath(path string) string

NormalizePagePath strips trailing "/index" from a page path for URL generation. "index" → "" "guides/index" → "guides" "guides/advanced" → "guides/advanced"

func PageURL

func PageURL(path string) string

PageURL returns the full URL for a docs page path.

func ParseKeywords

func ParseKeywords(raw string) []string

ParseKeywords splits a frontmatter `keywords:` value (comma or space separated) into a slice of trimmed keywords.

func PathToTitle

func PathToTitle(path string) string

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

func StripFrontmatter(src string) string

StripFrontmatter removes YAML frontmatter from markdown content.

func StripHTMLTags

func StripHTMLTags(s string) string

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

type Badge struct {
	Text    string `json:"text"`
	Variant string `json:"variant,omitempty"`
}

Badge is a small colored chip rendered next to a sidebar link or page heading.

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 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 with JSX support. The result is identical to ParseMD since both delegate to the same markdown renderer.

type HeadTag added in v0.4.0

type HeadTag struct {
	Tag   string
	Attrs map[string]string
}

HeadTag is a per-page <tag attrs /> rendered in the page <Head>.

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 struct {
	Disabled bool
	Text     string
	Link     string
}

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.

func Scan

func Scan(cfg Config) ([]Page, error)

Scan walks the content directory and parses all .md/.mdx files.

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.

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 {
	Label       string
	Order       int
	Hidden      bool
	Badge       *Badge
	Collapsible bool
	DefaultOpen bool
	Icon        string
}

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

func ExtractTOC(html string) []TOCItem

ExtractTOC parses rendered HTML and extracts the default heading range (h2–h3) for the TOC sidebar.

func ExtractTOCLevels added in v0.4.0

func ExtractTOCLevels(html string, minLevel, maxLevel int) []TOCItem

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).

type TocConfig added in v0.4.0

type TocConfig struct {
	Disabled bool
	MinLevel int
	MaxLevel int
	Label    string
}

TocConfig controls the page's table of contents.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL