engine

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Aug 4, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var AllowedHeadTags = map[string]bool{
	"meta": true, "link": true, "script": true,
	"style": true, "noscript": true, "base": true,
}

AllowedHeadTags lists the HTML tag names permitted in per-page head injection.

View Source
var ValidDirectiveFieldPlacements = map[string]bool{
	"attr": true, "bare-flag": true, "quoted-flag": true, "bare-icon": true, "paren-flag": true,
}

ValidDirectiveFieldPlacements is the set of allowed CatalogDirectiveField.Placement values.

View Source
var ValidDirectiveFieldTypes = map[string]bool{
	"string": true, "enum": true, "boolean": true, "number": true, "icon": true,
}

ValidDirectiveFieldTypes is the set of allowed CatalogDirectiveField.Type values. Shared by the catalog parity tests and the generic directive loader (internal/directive) so both validate against one source of truth.

View Source
var VariantAliases = map[string]BadgeVariant{
	"green": BadgeVariantTip,
	"amber": BadgeVariantCaution,
	"red":   BadgeVariantDanger,
}

VariantAliases maps legacy color names to semantic variants.

Functions

func LayoutHasSidebar

func LayoutHasSidebar(layout LayoutType) bool

LayoutHasSidebar returns true if the layout includes a sidebar.

func LayoutHasTOC

func LayoutHasTOC(layout LayoutType) bool

LayoutHasTOC returns true if the layout includes a table of contents.

func ResolvePageVersion

func ResolvePageVersion(page *Page) string

ResolvePageVersion returns the version string to pass to the URL resolver. Returns "" for unversioned pages or latest-version pages (produces the unprefixed alias URL). Returns the version ID for older versions.

func SectionDepth added in v1.0.0

func SectionDepth(sec *Section) int

SectionDepth returns the nesting depth of a section (root = 0).

func ValidateLayout

func ValidateLayout(layout LayoutType) bool

ValidateLayout returns true if the layout type is recognized.

Types

type Badge

type Badge struct {
	Text    string       `yaml:"text"`
	Variant BadgeVariant `yaml:"variant"`
}

Badge represents a sidebar badge with a display label and a semantic variant.

Supports two YAML forms:

badge: "New"                    → Badge{Text: "New", Variant: "default"}
badge:
  text: "New"
  variant: "tip"                → Badge{Text: "New", Variant: "tip"}

func (Badge) CSSClass

func (b Badge) CSSClass() string

CSSClass returns the CSS class for the badge variant (e.g. "sarde-badge-tip").

func (Badge) IsEmpty

func (b Badge) IsEmpty() bool

func (*Badge) UnmarshalYAML

func (b *Badge) UnmarshalYAML(value *yaml.Node) error

type BadgeVariant

type BadgeVariant string

BadgeVariant is a semantic label for a sidebar badge's color scheme.

const (
	BadgeVariantDefault BadgeVariant = "default"
	BadgeVariantNote    BadgeVariant = "note"
	BadgeVariantTip     BadgeVariant = "tip"
	BadgeVariantSuccess BadgeVariant = "success"
	BadgeVariantCaution BadgeVariant = "caution"
	BadgeVariantDanger  BadgeVariant = "danger"
)
type BreadcrumbItem struct {
	Label   string
	URL     string
	Current bool
}

BreadcrumbItem is a single entry in a breadcrumb trail.

type BuildLogEntry

type BuildLogEntry struct {
	Source  string // e.g. "sitemap", "search", "social-cards"
	Message string
}

BuildLogEntry is a single log message emitted during the build.

type BuildLogger

type BuildLogger struct {
	// contains filtered or unexported fields
}

BuildLogger collects log messages from the build pipeline and plugins. Thread-safe for use from parallel BuildDone plugin goroutines.

func NewBuildLogger

func NewBuildLogger() *BuildLogger

NewBuildLogger creates an empty BuildLogger.

func (*BuildLogger) Log

func (l *BuildLogger) Log(source, message string)

Log records a message from the given source.

func (*BuildLogger) Messages

func (l *BuildLogger) Messages() []BuildLogEntry

Messages returns all collected log entries.

type BuildResult

type BuildResult struct {
	PageCount int
	Duration  time.Duration
	Warnings  []ValidationWarning
	OutputDir string

	// Summary stats (populated by full Build(), zero for incremental ContentRebuild).
	PaginatorPages  int
	Collections     int
	BundleAssets    int
	PublicFiles     int
	ProcessedImages int
	AliasCount      int
	SitemapCount    int

	// Build logging.
	LogMessages  []BuildLogEntry
	PhaseTimings []PhaseTiming
}

BuildResult holds the outcome of a site build.

type CatalogCategory added in v1.0.0

type CatalogCategory struct {
	Name      string         `yaml:"name" json:"name"`
	Label     string         `yaml:"label" json:"label"`
	Nested    bool           `yaml:"nested" json:"nested,omitempty"`
	ParentKey string         `yaml:"parent_key" json:"parentKey,omitempty"`
	Fields    []CatalogField `yaml:"fields" json:"fields"`
}

CatalogCategory groups related frontmatter fields. Nested categories (sidebar, toc) describe the children of a single top-level mapping key named by ParentKey.

type CatalogCollectionType added in v1.0.0

type CatalogCollectionType struct {
	Names           []string `yaml:"names" json:"names"`
	Layout          string   `yaml:"layout" json:"layout"`
	ExtraCategories []string `yaml:"extra_categories" json:"extraCategories,omitempty"`
}

CatalogCollectionType holds name-based inference hints for a collection type (mirroring internal/collection/infer.go): matching names, the layout that type infers to, and extra field categories granted to matching collections regardless of layout.

type CatalogDirective added in v1.0.0

type CatalogDirective struct {
	Name        string `yaml:"name" json:"name"`
	Label       string `yaml:"label" json:"label"`
	Description string `yaml:"description" json:"description"`
	Kind        string `yaml:"kind" json:"kind"` // "callout" | "block"

	// Source identifies where the directive comes from: "builtin" for the
	// embedded catalog, "site" or "theme" for generic directives loaded from
	// a directives/ folder. Empty in the embedded YAML; stamped when catalogs
	// are merged (internal/directive MergeCatalog).
	Source string `yaml:"source,omitempty" json:"source,omitempty"`

	// Bracket describes [Title]/[Summary]/[Label] support. Nil when the
	// directive's grammar has no bracket group at all (e.g. badge, video).
	Bracket *CatalogDirectiveBracket `yaml:"bracket,omitempty" json:"bracket,omitempty"`

	// Fields are attr/flag fields only, never the bracket. Order is the
	// picker form's display order.
	Fields []CatalogDirectiveField `yaml:"fields,omitempty" json:"fields,omitempty"`

	// BodyTemplate is literal body text (may contain ${...} editor snippet
	// placeholders). Empty for leaf directives with no body (video,
	// link-button, link-card) and for container directives.
	BodyTemplate string `yaml:"body_template,omitempty" json:"bodyTemplate,omitempty"`

	// ChildTemplate describes a repeatable nested child block for container
	// directives; a literal "N" token is replaced with the 1-based index.
	// ChildCountField optionally names the field whose value drives the
	// repeat count (falling back to ChildDefaultCount).
	ChildTemplate     string `yaml:"child_template,omitempty" json:"childTemplate,omitempty"`
	ChildDefaultCount int    `yaml:"child_default_count,omitempty" json:"childDefaultCount,omitempty"`
	ChildCountField   string `yaml:"child_count_field,omitempty" json:"childCountField,omitempty"`
}

CatalogDirective describes one ::: block directive's syntax: its exact fence name, the optional [bracket] group, the attr/flag fields on the opening fence, and either a literal body template or a repeatable child block template for container directives.

type CatalogDirectiveBracket added in v1.0.0

type CatalogDirectiveBracket struct {
	Label       string `yaml:"label" json:"label"`
	Required    bool   `yaml:"required" json:"required"` // figure only: brackets mandatory (may be empty)
	Placeholder string `yaml:"placeholder" json:"placeholder"`
}

CatalogDirectiveBracket describes the [bracket] group on an opening fence.

type CatalogDirectiveField added in v1.0.0

type CatalogDirectiveField struct {
	Name        string   `yaml:"name" json:"name"`
	Label       string   `yaml:"label" json:"label"`
	Type        string   `yaml:"type" json:"type"`           // string | enum | boolean | number | icon
	Placement   string   `yaml:"placement" json:"placement"` // attr | bare-flag | quoted-flag | bare-icon | paren-flag
	Options     []string `yaml:"options,omitempty" json:"options,omitempty"`
	Default     string   `yaml:"default,omitempty" json:"default,omitempty"`
	Required    bool     `yaml:"required,omitempty" json:"required,omitempty"`
	Placeholder string   `yaml:"placeholder,omitempty" json:"placeholder,omitempty"`
}

CatalogDirectiveField is one attr/flag on the opening fence. Placement controls the exact emitted syntax — see directive_catalog.yaml's header.

type CatalogField added in v1.0.0

type CatalogField struct {
	Key         string         `yaml:"key" json:"key"`
	Type        string         `yaml:"type" json:"type"`
	Label       string         `yaml:"label" json:"label,omitempty"`
	Description string         `yaml:"description" json:"description,omitempty"`
	Required    bool           `yaml:"required" json:"required,omitempty"`
	Unrendered  bool           `yaml:"unrendered" json:"unrendered,omitempty"`
	Default     any            `yaml:"default" json:"default,omitempty"`
	Min         *float64       `yaml:"min" json:"min,omitempty"`
	Max         *float64       `yaml:"max" json:"max,omitempty"`
	MaxLength   *int           `yaml:"max_length" json:"maxLength,omitempty"`
	Options     []string       `yaml:"options" json:"options,omitempty"`
	Fields      []CatalogField `yaml:"fields" json:"fields,omitempty"`
	Items       []CatalogField `yaml:"items" json:"items,omitempty"`
}

CatalogField describes one frontmatter field: its key, widget type, human-facing label/description, and constraints. Object fields list their children in Fields; list-of-object fields describe item shape in Items. Unrendered marks fields the engine parses but no template renders yet — UIs should hide these from field pickers.

type CollectedLink struct {
	Href    string
	IsImage bool
}

CollectedLink represents a link found during markdown rendering.

type Collection

type Collection struct {
	Name      string
	Title     string
	Config    *CollectionConfig
	Pages     []*Page
	Featured  []*Page // subset of Pages with frontmatter `featured: true`
	Sections  []*Section
	NavTree   *NavTree            // default language nav tree (backward compat)
	NavTrees  map[string]*NavTree // per-language nav trees (i18n)
	IndexPage *Page
	IsTabbed  bool       // true when docs tabs are auto-detected or forced
	Tabs      []*DocsTab // ordered by weight, then title

	// Versioning
	Versioning        *VersionConfig
	CompositeNavTrees map[string]*NavTree   // keyed by langVersionKey(lang, ver) for versioned collections
	CompositeTabSets  map[string][]*DocsTab // keyed by langVersionKey(lang, ver) for versioned+tabbed collections

	// Labs
	LabNavTrees   map[string]*NavTree // keyed by lab section permalink, for lab-scoped sidebar
	IsMultiCourse bool                // true when the labs collection has a course grouping layer
}

Collection represents a group of pages (blog, docs, courses, etc.).

type CollectionConfig

type CollectionConfig struct {
	SortBy     string
	SortOrder  string
	Layout     LayoutType
	Permalink  string
	Paginate   int
	Feed       bool
	Sidebar    *SidebarConfig
	TOC        *TOCConfig
	PrevNext   *PrevNextConfig
	Tabs       *bool          // nil = auto-detect, true = force tabs, false = disable tabs
	Versioning *VersionConfig // nil = no versioning
	Labs       *LabsConfig    // nil = not a labs collection
}

CollectionConfig holds per-collection settings (auto-detected or explicit).

type DirectiveCatalog added in v1.0.0

type DirectiveCatalog struct {
	Categories []DirectiveCategory `yaml:"categories" json:"categories"`
}

DirectiveCatalog is the canonical description of every ::: block directive Sarde recognizes, grouped into categories. It is the single source of truth consumed by `sarde directives` and Sarde Studio's directive picker, and is built from each extension's parser grammar (internal/content/markdown/extensions/<name>/parser.go), not the docs.

func LoadDirectiveCatalog added in v1.0.0

func LoadDirectiveCatalog() (*DirectiveCatalog, error)

LoadDirectiveCatalog parses the embedded directive catalog. The result is memoized; the embedded YAML cannot change at runtime.

type DirectiveCategory added in v1.0.0

type DirectiveCategory struct {
	Name       string             `yaml:"name" json:"name"`
	Label      string             `yaml:"label" json:"label"`
	Directives []CatalogDirective `yaml:"directives" json:"directives"`
}

DirectiveCategory groups related directives for display.

type DocsTab

type DocsTab struct {
	Title       string
	Description string
	Icon        string // emoji, icon name, or SVG path
	Slug        string // directory name, used for URL prefix matching
	Order       int
	Permalink   string   // URL of the tab's index page
	Section     *Section // the top-level section backing this tab
	NavTree     *NavTree
	NavTrees    map[string]*NavTree // per-language (i18n)
	Pages       []*Page
	IndexPage   *Page
}

DocsTab represents one tab in a tabbed docs collection. Each tab corresponds to a top-level subdirectory with its own nav tree.

type EditURLValue

type EditURLValue struct {
	Disabled  bool
	CustomURL string
}

EditURLValue represents the per-page edit_url frontmatter field.

Supports three YAML forms:

edit_url: false            → suppress the edit link
edit_url: true             → use the site-wide edit URL (default)
edit_url: "https://..."    → custom URL for this page

func (*EditURLValue) UnmarshalYAML

func (e *EditURLValue) UnmarshalYAML(value *yaml.Node) error

type FieldDef

type FieldDef struct {
	Type      string   `yaml:"type"       json:"type"` // "string", "int", "float", "bool", "date", "list", "enum"
	Label     string   `yaml:"label"      json:"label,omitempty"`
	Required  bool     `yaml:"required"   json:"required,omitempty"`
	Default   any      `yaml:"default"    json:"default,omitempty"`
	Min       *float64 `yaml:"min"        json:"min,omitempty"`
	Max       *float64 `yaml:"max"        json:"max,omitempty"`
	MaxLength *int     `yaml:"max_length" json:"maxLength,omitempty"`
	Options   []string `yaml:"options"    json:"options,omitempty"` // for enum type
}

FieldDef describes a single frontmatter field for validation and editor UI.

type FlexDate added in v1.0.0

type FlexDate struct {
	time.Time
}

FlexDate is a frontmatter date field that tolerates an unset value.

An empty, whitespace-only, or null value decodes as the zero time, meaning "not set", instead of failing the parse. Editors that clear a date field commonly write `date: ”`, and a single such file must not abort the build.

Accepted forms are the YAML native timestamp, RFC 3339, and plain YYYY-MM-DD (with an optional time component). Anything else is an error.

func (FlexDate) MarshalYAML added in v1.0.0

func (d FlexDate) MarshalYAML() (any, error)

MarshalYAML emits the zero time as an absent value so a round-trip through YAML does not turn "unset" into a year-1 timestamp.

func (*FlexDate) UnmarshalYAML added in v1.0.0

func (d *FlexDate) UnmarshalYAML(value *yaml.Node) error

type Frontmatter

type Frontmatter struct {
	FrontmatterIdentity `yaml:",inline"`
	FrontmatterMeta     `yaml:",inline"`
	Sidebar             FrontmatterSidebar `yaml:"sidebar"`
	TOC                 FrontmatterTOC     `yaml:"toc"`
	FrontmatterNav      `yaml:",inline"`

	Tags               []string       `yaml:"tags"`
	Categories         []string       `yaml:"categories"`
	ShowTags           *bool          `yaml:"show_tags"`
	Transparent        bool           `yaml:"transparent"`
	Hero               *HeroConfig    `yaml:"hero"`
	Icon               string         `yaml:"icon"`
	Head               []HeadTag      `yaml:"head"`
	Banner             *PageBanner    `yaml:"banner"`
	OGCard             *OGCard        `yaml:"og_card"`
	Cascade            map[string]any `yaml:"cascade"`
	Params             map[string]any `yaml:"params"`
	LearningObjectives []string       `yaml:"learning_objectives"`
}

Frontmatter represents parsed frontmatter fields from a content file. Sub-structs are embedded so all fields remain accessible as top-level names (e.g. fm.Title, fm.Draft, fm.Sidebar.Label).

type FrontmatterCatalog added in v1.0.0

type FrontmatterCatalog struct {
	Layouts         map[string][]string              `yaml:"layouts" json:"layouts"`
	CollectionTypes map[string]CatalogCollectionType `yaml:"collection_types" json:"collectionTypes"`
	Categories      []CatalogCategory                `yaml:"categories" json:"categories"`
}

FrontmatterCatalog is the canonical description of every frontmatter field Sarde recognizes, grouped into categories, with a mapping from each implemented layout to the categories available on it. It is the single source of truth consumed by `sarde catalog` and Sarde Studio, and parity with the validator's known-key sets is enforced by tests.

func LoadFrontmatterCatalog added in v1.0.0

func LoadFrontmatterCatalog() (*FrontmatterCatalog, error)

LoadFrontmatterCatalog parses the embedded catalog. The result is memoized; the embedded YAML cannot change at runtime.

type FrontmatterIdentity

type FrontmatterIdentity struct {
	Title       string   `yaml:"title"`
	Slug        string   `yaml:"slug"`
	Date        FlexDate `yaml:"date"`
	Updated     FlexDate `yaml:"updated"`
	PublishDate FlexDate `yaml:"publish_date"`
	ExpiryDate  FlexDate `yaml:"expiry_date"`
	Aliases     []string `yaml:"aliases"`
	Layout      string   `yaml:"layout"`
	Type        string   `yaml:"type"`
	Template    string   `yaml:"template"`
}

FrontmatterIdentity holds core identity fields parsed from frontmatter.

type FrontmatterMeta

type FrontmatterMeta struct {
	Draft       bool          `yaml:"draft"`
	Description string        `yaml:"description"`
	Image       string        `yaml:"image"`
	Summary     string        `yaml:"summary"`
	Render      *bool         `yaml:"render"`
	Pagefind    *bool         `yaml:"pagefind"`
	ShowUpdated *bool         `yaml:"show_updated"`
	EditURL     *EditURLValue `yaml:"edit_url"`
}

FrontmatterMeta holds editorial and behavioral override fields.

type FrontmatterNav

type FrontmatterNav struct {
	Prev *NavOverride `yaml:"prev"`
	Next *NavOverride `yaml:"next"`
}

FrontmatterNav holds prev/next navigation override fields.

type FrontmatterSchema

type FrontmatterSchema struct {
	Fields map[string]FieldDef `yaml:"fields" json:"fields"`
}

FrontmatterSchema defines the expected frontmatter fields for a collection.

type FrontmatterSidebar

type FrontmatterSidebar struct {
	Order  int               `yaml:"order"`
	Label  string            `yaml:"label"`
	Hidden bool              `yaml:"hidden"`
	Attrs  map[string]string `yaml:"attrs"`
	Badge  Badge             `yaml:"badge"`
	Icon   string            `yaml:"icon"`
}

FrontmatterSidebar holds sidebar presentation fields.

type FrontmatterTOC

type FrontmatterTOC struct {
	Enabled  *bool `yaml:"enabled"`
	MinLevel int   `yaml:"min_level"`
	MaxLevel int   `yaml:"max_level"`
}

FrontmatterTOC holds table-of-contents override fields.

Supports two YAML forms:

toc: false                      → FrontmatterTOC{Enabled: ptr(false)}
toc:
  enabled: true
  min_level: 2                  → FrontmatterTOC{Enabled: ptr(true), MinLevel: 2}

func (*FrontmatterTOC) UnmarshalYAML

func (t *FrontmatterTOC) UnmarshalYAML(value *yaml.Node) error
type GlobalNav struct {
	Items []GlobalNavItem
}

GlobalNav represents the top-level site navigation bar.

type GlobalNavItem struct {
	Label      string
	URL        string
	Collection string
	IsActive   bool
	External   bool
}

GlobalNavItem is a single entry in the global navigation bar.

type HeadTag

type HeadTag struct {
	Tag     string            `yaml:"tag"`
	Attrs   map[string]string `yaml:"attrs"`
	Content string            `yaml:"content"`
}

HeadTag defines a single injected <head> element from frontmatter.

type Heading

type Heading struct {
	Level int
	ID    string
	Text  string
}

Heading represents a heading extracted from content for ToC generation.

type HeroAction

type HeroAction struct {
	Text    string            `yaml:"text"`
	Link    string            `yaml:"link"`
	Variant string            `yaml:"variant"`
	Icon    string            `yaml:"icon"`
	Attrs   map[string]string `yaml:"attrs"`
}

HeroAction defines a call-to-action button in the hero section.

type HeroCTAData

type HeroCTAData struct {
	Label string
	URL   string
	Icon  string
}

HeroCTAData holds the call-to-action button settings.

type HeroCodeData

type HeroCodeData struct {
	Title    string
	Language string
	Body     string
}

HeroCodeData holds the optional code sample shown in the homepage hero.

type HeroConfig

type HeroConfig struct {
	Title   string       `yaml:"title"`
	Tagline string       `yaml:"tagline"`
	Image   *HeroImage   `yaml:"image"`
	Actions []HeroAction `yaml:"actions"`
}

HeroConfig defines hero section fields for splash layout pages.

func (*HeroConfig) SanitizeAttrs

func (h *HeroConfig) SanitizeAttrs()

SanitizeAttrs strips event-handler attributes (on*) from all hero actions.

type HeroData

type HeroData struct {
	Eyebrow      string
	Title        string
	Subtitle     string
	CTA          *HeroCTAData
	SecondaryCTA *HeroCTAData
	Stats        []HeroStatData
	Code         *HeroCodeData
	Image        *HeroImageData
	Background   string
}

HeroData holds hero section settings for the homepage.

type HeroImage

type HeroImage struct {
	Src   string `yaml:"src"`
	Light string `yaml:"light"`
	Dark  string `yaml:"dark"`
	Alt   string `yaml:"alt"`
}

HeroImage defines the hero image with optional light/dark variants.

type HeroImageData

type HeroImageData struct {
	Src   string
	Light string
	Dark  string
	Alt   string
	HTML  template.HTML
}

HeroImageData holds the optional hero image/SVG for the homepage hero panel.

type HeroStatData

type HeroStatData struct {
	Value string
	Label string
}

HeroStatData holds a short proof point for the homepage hero.

type HomepageData

type HomepageData struct {
	Template string
	Hero     HeroData
}

HomepageData exposes homepage settings to templates.

type IconLicense

type IconLicense struct {
	Prefix string
	Title  string
	SPDX   string
	URL    string
}

IconLicense is the license metadata of a loaded icon set, exposed to templates as .Site.IconLicenses so a theme/author can render a credits page.

type LabsConfig added in v1.0.0

type LabsConfig struct {
	StepLabel string // "Lab" (default), configurable to "Exercise", "Activity", etc.
}

LabsConfig holds labs-collection-specific settings.

type Language

type Language struct {
	Code   string
	Name   string
	Dir    string // "ltr" or "rtl"
	Weight int
}

Language represents a configured language for i18n.

type LayoutType

type LayoutType string

LayoutType determines the page layout (column structure).

const (
	LayoutDefault      LayoutType = "default"      // single-column (blog, projects, standalone)
	LayoutDocs         LayoutType = "docs"         // three-column (sidebar | content | ToC)
	LayoutSplash       LayoutType = "splash"       // full-width, no sidebar or ToC (landing pages)
	LayoutWide         LayoutType = "wide"         // wider content with sidebar, no ToC
	LayoutFull         LayoutType = "full"         // full-width, no sidebar or ToC
	LayoutCentered     LayoutType = "centered"     // narrow centered column, no sidebar
	LayoutSplit        LayoutType = "split"        // two equal columns; no sidebar, no ToC
	LayoutPresentation LayoutType = "presentation" // full-width slide-viewer; no sidebar, no ToC
	LayoutLabs         LayoutType = "labs"         // lab reader; sidebar + ToC + progress bar
)

func ResolveLayout

func ResolveLayout(s string) LayoutType

ResolveLayout converts a string to a validated LayoutType, falling back to LayoutDefault.

type LogoContext added in v1.1.0

type LogoContext struct {
	Light         LogoImage
	Dark          LogoImage
	Alt           string
	ReplacesTitle bool
	// Single reports that one image serves both themes, so the template renders
	// a single <img> with no light/dark toggle classes.
	Single bool
}

LogoContext carries the resolved site logo into templates as .Site.Logo.

type LogoImage added in v1.1.0

type LogoImage struct {
	URL    string
	Width  int
	Height int
}

LogoImage is one resolved logo variant. Width and Height are 0 for SVG logos and whenever the dimensions could not be probed, in which case the template omits the corresponding attributes.

type MarkdownRenderer

type MarkdownRenderer interface {
	Render(markdown string) (RenderResult, error)
}

MarkdownRenderer converts Markdown content to HTML via the Goldmark pipeline. Used as a parameter type by shortcode/processor to decouple from content/markdown.

type NavNode struct {
	Label       string
	URL         string
	Slug        string
	Order       int
	Position    int
	Children    []*NavNode
	Parent      *NavNode
	Depth       int
	IsActive    bool
	IsOpen      bool
	HasActive   bool
	DefaultOpen bool
	GroupIndex  int
	Page        *Page
	Attrs       map[string]string
	Icon        string
	Badge       Badge
	Description string
}

NavNode is a single entry in the sidebar navigation tree.

type NavOverride struct {
	Disabled bool   `yaml:"-"`
	Slug     string `yaml:"-"`
	Link     string `yaml:"link"`
	Label    string `yaml:"label"`
}

NavOverride represents a per-page prev/next frontmatter override.

Supports three YAML forms:

prev: false                             → suppress the nav link
prev: "some-slug"                       → use page with this slug
prev: { link: "/url/", label: "..." }   → explicit URL + label
func (n *NavOverride) UnmarshalYAML(value *yaml.Node) error
type NavTree struct {
	Root       *NavNode
	Flat       []*NavNode
	TotalPages int
	MaxDepth   int
	Hash       string
}

NavTree represents a complete sidebar navigation tree for a collection.

type NodeKind

type NodeKind string

NodeKind classifies content files discovered during the filesystem walk.

const (
	KindHome       NodeKind = "home"
	KindSection    NodeKind = "section"
	KindPage       NodeKind = "page"
	KindBundle     NodeKind = "bundle"
	KindStandalone NodeKind = "standalone"
	KindTaxonomy   NodeKind = "taxonomy"
	KindTerm       NodeKind = "term"
)

type OGCard added in v1.2.0

type OGCard struct {
	BgColor       string `yaml:"bg_color"`
	AccentColor   string `yaml:"accent_color"`
	AccentColor2  string `yaml:"accent_color_2"`
	TextColor     string `yaml:"text_color"`
	HideWatermark bool   `yaml:"hide_watermark"`
}

OGCard holds per-page social card overrides from the og_card frontmatter block. Scope is deliberately colors and toggles only: text on the card always comes from the page's own title and description. Empty color fields fall back to the social_cards plugin config.

type Page

type Page struct {
	PageIdentity
	PageContent
	PageMeta
	PageRelationships
	PageTaxonomy
	Sidebar PageSidebar
	TOC     PageTOC
	PageI18n
	PageVersioning

	ShowTags *bool

	NavNode   *NavNode
	Resources []Resource
	Params    map[string]any
}

Page represents a single content page. Sub-structs are embedded so all fields remain accessible as top-level names (e.g. page.Title, page.Tags).

func (*Page) ShowUpdated added in v1.1.0

func (p *Page) ShowUpdated() bool

ShowUpdated reports whether the page's Updated timestamp should be surfaced to visitors, from the show_updated frontmatter field (default true).

This gates display only. Updated is always resolved as data, so sitemap lastmod, SEO dateModified, and feed timestamps stay correct on pages whose badge is hidden.

type PageBanner

type PageBanner struct {
	Content string `yaml:"content"`
	Variant string `yaml:"variant"` // note | tip | caution | danger (defaults to "note")
	Icon    string `yaml:"icon"`    // Lucide icon name; overrides the variant's default icon
}

PageBanner defines a per-page announcement banner from frontmatter.

Supports one YAML form:

banner:
  content: "This page is under construction"
  variant: "caution"
  icon: "construction"

type PageContent

type PageContent struct {
	Content           template.HTML
	Summary           template.HTML
	RawContent        string
	ContentDigest     string // hex digest of raw file bytes (for incremental rebuild skip)
	FrontmatterDigest string // hex digest of serialized frontmatter map (body-only change detection)
	WordCount         int
	ReadingTime       int
	Headings          []Heading
	HasCodeBlocks     bool
	HasImages         bool
	FrontmatterLines  int
}

PageContent holds rendered content and content-derived metadata.

type PageI18n

type PageI18n struct {
	Lang            string
	LangRelPath     string
	Translations    []*Page
	AllTranslations []*Page
	IsFallback      bool
}

PageI18n holds language and translation fields.

type PageIdentity

type PageIdentity struct {
	Title        string
	Slug         string
	Date         time.Time
	Updated      time.Time
	PublishDate  time.Time
	ExpiryDate   time.Time
	Permalink    string
	RelPermalink string
	Kind         NodeKind
	FilePath     string
	RelPath      string
}

PageIdentity holds the core identity fields of a page.

func (*PageIdentity) URL

func (p *PageIdentity) URL() string

URL returns the resolved Permalink if set, otherwise RelPermalink. In a fully built site, Permalink is always set. This accessor exists for robustness in tests and edge cases where Permalink may be empty.

type PageMeta

type PageMeta struct {
	Draft       bool
	Description string
	Image       string

	// DateExplicit reports whether Date came from an explicit source (a
	// frontmatter "date" key or a YYYY-MM-DD filename prefix) rather than
	// being inferred from file modification time. Consumers that display
	// dates as editorial content (e.g. social cards) should check this to
	// avoid presenting an mtime as a publish date.
	DateExplicit bool
}

PageMeta holds editorial metadata.

type PageRelationships

type PageRelationships struct {
	Collection *Collection
	Section    *Section
	PrevPage   *Page
	NextPage   *Page
	Siblings   []*Page
	Backlinks  []*Page
}

PageRelationships holds graph connections to other pages and structures.

type PageSidebar

type PageSidebar struct {
	Order  int
	Label  string
	Hidden bool
	Attrs  map[string]string
	Badge  Badge
	Icon   string
}

PageSidebar holds sidebar presentation fields.

type PageTOC

type PageTOC struct {
	Enabled  *bool
	MinLevel int
	MaxLevel int
}

PageTOC holds per-page table-of-contents override fields.

type PageTaxonomy

type PageTaxonomy struct {
	Tags       []string
	Categories []string
	Aliases    []string
	Extra      map[string][]string
}

PageTaxonomy holds taxonomy membership fields.

type PageVersioning

type PageVersioning struct {
	Version        string
	VersionRelPath string
	VersionPeers   []*Page
}

PageVersioning holds version membership fields.

type PaginationLink struct {
	URL   string
	Title string
}

PaginationLink is a reference to a prev or next page.

type PaginationLinks struct {
	Prev *PaginationLink
	Next *PaginationLink
}

PaginationLinks holds prev/next page references.

type Paginator

type Paginator struct {
	Pages        []PaginationLink // Numbered links (one per page of results)
	CurrentPages []*Page          // Slice of content pages visible on this pagination page
	Current      int              // 1-based index of the current page
	Total        int              // Total number of pagination pages
	HasPrev      bool
	HasNext      bool
	PrevURL      string
	NextURL      string
	TotalItems   int    // Total content items across all pagers
	BaseURL      string // Collection base URL for constructing custom pagination links
	FirstURL     string // Permalink to the first pagination page
	LastURL      string // Permalink to the last pagination page
}

Paginator holds numbered list-page pagination state for collection index pages.

type PhaseTiming

type PhaseTiming struct {
	Phase    string
	Duration time.Duration
}

PhaseTiming records the duration of a single build pipeline phase.

type PrevNextConfig

type PrevNextConfig struct {
	Enabled bool
	Labels  [2]string
}

PrevNextConfig controls prev/next navigation links.

type RenderResult

type RenderResult struct {
	HTML          string
	Headings      []Heading
	HasCodeBlocks bool
	HasImages     bool
	Links         []CollectedLink
}

RenderResult holds the output of a markdown-to-HTML conversion.

type Resource

type Resource struct {
	Name         string
	Title        string
	MediaType    string
	RelPermalink string
	Width        int
	Height       int
	SrcPath      string // absolute filesystem path for image processing
}

Resource represents a page-bundled asset (image, file, etc.).

type RouteAssets

type RouteAssets struct {
	Scripts       []string
	Styles        []string
	InlineScripts []template.JS
	ModuleScripts []string
}

RouteAssets holds per-page asset URLs injected by plugins via BeforeRender.

type RouteData

type RouteData struct {
	Page       *Page
	Collection *Collection
	Site       *SiteContext
	Theme      *ThemeConfig
	Layout     LayoutType
	Template   string

	RouteNav
	RouteI18n
	RouteVersioning
	RouteTabs
	RouteLabs
	RouteAssets

	Homepage     *HomepageData
	Taxonomy     *Taxonomy
	TaxonomyTerm *TaxonomyTerm
	TermEntries  []*TermEntry
	PageBanner   *PageBanner
}

RouteData is the unified context object passed to every template render. Sub-structs are embedded so all fields remain accessible as top-level names in both Go code and html/template (e.g. .Lang, .Scripts, .Version).

type RouteI18n

type RouteI18n struct {
	Lang            string
	Dir             string
	Translations    []TranslationLink
	AllTranslations []TranslationLink
}

RouteI18n groups language and translation fields.

type RouteLabs added in v1.0.0

type RouteLabs struct {
	LabNumber          int
	LabStepIndex       int
	LabStepTotal       int
	LabStepLabel       string
	LearningObjectives []string
}

RouteLabs groups lab-collection fields (progress, numbering, objectives).

type RouteNav

type RouteNav struct {
	GlobalNav                 *GlobalNav
	Sidebar                   *NavTree
	SidebarType               string
	Breadcrumbs               []BreadcrumbItem
	Pagination                *PaginationLinks
	Paginator                 *Paginator
	HasSidebar                bool
	SidebarCollapsedByDefault bool
	Section                   *Section
	IsSection                 bool
}

RouteNav groups navigation-related fields for the current page render.

type RouteTabs

type RouteTabs struct {
	IsTabbed  bool
	DocsTabs  []*DocsTab
	ActiveTab *DocsTab
}

RouteTabs groups docs-tab fields for tabbed collections.

type RouteVersioning

type RouteVersioning struct {
	Version       string
	VersionLabel  string
	Versions      []VersionLink
	IsLatest      bool
	VersionBanner string
}

RouteVersioning groups version-switcher fields for versioned collections.

type Section

type Section struct {
	Title       string
	Slug        string
	Permalink   string
	Pages       []*Page
	Sections    []*Section
	IndexPage   *Page
	Parent      *Section
	Collection  *Collection
	Transparent bool
	Render      bool
}

Section represents a directory with child pages and sub-sections.

type SidebarConfig

type SidebarConfig struct {
	Collapsible        bool
	CollapsedByDefault bool
	MaxDepth           int
	Search             bool

	// CollapseLevel, when > 0, expands groups at depth <= N by default and
	// collapses deeper groups. 0 = unset (CollapsedByDefault governs).
	CollapseLevel int

	// Overrides holds sidebar.yaml path-keyed node overrides
	// (collection-relative path -> override). Nil unless sidebar.yaml sets any.
	Overrides map[string]*SidebarOverride

	// TabOverrides holds sidebar.yaml tab-bar overrides (tab slug -> override).
	TabOverrides map[string]*TabOverride
	// contains filtered or unexported fields
}

SidebarConfig controls sidebar behavior for docs-layout collections.

func (*SidebarConfig) MarkOverrideMatched added in v1.0.0

func (s *SidebarConfig) MarkOverrideMatched(key string)

MarkOverrideMatched records that a sidebar.yaml override key was consulted during nav-tree building. A key is only reported unmatched when no lane (language/version combination) ever matched it. Nav-tree assembly is serial, so no locking is needed.

func (*SidebarConfig) MarkTabMatched added in v1.0.0

func (s *SidebarConfig) MarkTabMatched(key string)

MarkTabMatched records that a sidebar.yaml tab override key was consulted.

func (*SidebarConfig) UnmatchedOverrideKeys added in v1.0.0

func (s *SidebarConfig) UnmatchedOverrideKeys() []string

UnmatchedOverrideKeys returns the sorted override keys that no lane matched.

func (*SidebarConfig) UnmatchedTabKeys added in v1.0.0

func (s *SidebarConfig) UnmatchedTabKeys() []string

UnmatchedTabKeys returns the sorted tab override keys that no lane matched.

type SidebarOverride added in v1.0.0

type SidebarOverride struct {
	Label       string
	Description string
	Order       *int // nil = unset (0 is a valid explicit value)
	Collapsed   *bool
	Icon        string
	Badge       Badge
	Hidden      *bool // nil = unset; false un-hides a frontmatter-hidden page
	Attrs       map[string]string
}

SidebarOverride holds sidebar.yaml overrides for one path-keyed node (section or page). Unset fields fall through to the next precedence layer (frontmatter, then inferred defaults).

type SiteContext

type SiteContext struct {
	Title            string
	BaseURL          string
	BasePath         string // normalized: "/docs/" or "/"
	SiteID           string
	Language         string
	Generator        string
	Favicon          string
	FaviconType      string
	SitemapEnabled   bool
	Config           any // *config.SiteConfig at runtime; any to avoid circular imports
	Collections      map[string]*Collection
	Taxonomies       map[string]*Taxonomy
	TaxonomiesByLang map[string]map[string]*Taxonomy
	Pages            []*Page
	Data             map[string]any
	BuildTime        time.Time
	Languages        []Language
	DefaultLang      string
	EditURL          string        // base URL for "edit this page" links (e.g. https://github.com/user/repo/edit/main/content)
	KazariScriptURL  string        // URL of the Kazari interaction JS file served globally on every page
	IconLicenses     []IconLicense // license metadata for loaded icon sets (for an attribution/credits page)
}

SiteContext provides global site data accessible in every template.

type TOCConfig

type TOCConfig struct {
	Enabled         bool
	MinLevel        int
	MaxLevel        int
	ScrollHighlight bool
}

TOCConfig controls table of contents rendering.

type TabOverride added in v1.0.0

type TabOverride struct {
	Label       string
	Description string
	Icon        string
	Order       *int
}

TabOverride holds sidebar.yaml overrides for one docs tab (keyed by slug).

type Taxonomy

type Taxonomy struct {
	Name       string
	Singular   string
	Terms      map[string]*TaxonomyTerm
	Permalink  string
	PaginateBy int // 0 = no pagination for term listing pages
}

Taxonomy represents a grouping dimension (tags, categories, authors, etc.).

type TaxonomyTerm

type TaxonomyTerm struct {
	Name        string
	Slug        string
	CustomSlug  string // from permalink field in data/*.yml; overrides Slugify(Name)
	Permalink   string
	Pages       []*Page
	Label       string
	Description string
	Color       string
	Icon        string
	Hidden      bool
	Priority    int
	Difficulty  string // beginner, intermediate, advanced
	ContentType string // lecture, lab, assignment, project, reference, tutorial, assessment
}

TaxonomyTerm is a single term within a taxonomy with its associated pages.

type TermEntry

type TermEntry struct {
	*TaxonomyTerm
	Count   int
	PopTier int // 1-5 popularity quintile
}

TermEntry wraps a TaxonomyTerm with computed tag-cloud data.

type ThemeConfig

type ThemeConfig struct {
	Name        string
	Slug        string
	Version     string
	Author      string
	Tokens      map[string]string
	DarkTokens  map[string]string
	DarkEnabled bool
	StyleTag    template.HTML // pre-rendered <style> block with :root/:root[data-theme="dark"] tokens
}

ThemeConfig holds metadata, token values, and pre-rendered CSS for the active theme.

type ThemeResolver

type ThemeResolver struct {
	ProjectDir string   // root of user project (contains layouts/, themes/)
	ThemeName  string   // active theme name (for themes/<name>/layouts/)
	EmbeddedFS fs.FS    // compiled-in embedded/theme/ filesystem
	PluginDirs []string // templates/ dirs of active external plugins, sorted by slug
}

ThemeResolver handles template/asset overlay resolution. Priority order: user → theme → plugin → embedded.

type TranslationLink struct {
	Lang       string
	Name       string // display name (e.g. "Français"), falls back to Lang code
	Dir        string // "ltr" or "rtl"
	URL        string
	Title      string
	IsFallback bool
}

TranslationLink points to the same page in another language.

type URLResolver

type URLResolver struct {
	BasePath    string // normalized: "/docs/" or "/"
	BaseURL     string // origin only: "https://example.com"
	I18nEnabled bool
	DefaultLang string
	Strategy    string          // "prefix-except-default"
	Languages   map[string]bool // set of known language codes

	CollectionMounts []string        // ["/docs", "/blog"] — populated by builder
	VersionIDs       map[string]bool // union of all version IDs across versioned collections
}

URLResolver resolves site-root-relative, prefix-free paths into final URLs. It is the single chokepoint for basePath, lang, and version prefixing.

func (*URLResolver) AbsURL

func (r *URLResolver) AbsURL(relPath, lang, version string) string

AbsURL returns the fully-qualified URL (origin + resolved path).

func (*URLResolver) CacheKey

func (r *URLResolver) CacheKey() string

CacheKey returns a deterministic digest of every field that affects URL resolution. The page-render cache must fold this into its content hash: rendered HTML embeds resolved links, so a change to base path, base URL, i18n, version, or collection layout must bust otherwise-identical content. Maps are sorted so the key is stable across map-iteration order.

func (*URLResolver) IsVersionID

func (r *URLResolver) IsVersionID(seg string) bool

IsVersionID reports whether seg matches any configured version ID (union over all versioned collections).

func (*URLResolver) OutputRelPath

func (r *URLResolver) OutputRelPath(relPath, lang, version string) string

OutputRelPath returns the on-disk output path: version- and lang-prefixed but WITHOUT basePath. Used to compute filesystem write paths where version and lang create real directories but basePath does not (the web server's mount handles basePath).

func (*URLResolver) URL

func (r *URLResolver) URL(relPath, lang, version string) string

URL resolves a site-root-relative, prefix-free path to a final root-relative URL.

relPath: e.g. "/docs/guides/auth/" — always treated as site-root-relative. lang: language code; "" means default language. Non-default languages

get a /<lang>/ segment inserted (prefix-except-default strategy).

version: version ID for non-latest versions (e.g. "v1"); "" for latest/unversioned.

Inserted AFTER the collection mount, not as a global prefix.

type ValidationEntry

type ValidationEntry struct {
	Links    []CollectedLink
	FilePath string
	Lang     string
}

ValidationEntry holds collected links for a single page, used by the link validator.

type ValidationWarning

type ValidationWarning struct {
	File    string
	Field   string
	Message string
	Level   string
}

ValidationWarning represents a non-fatal issue found during frontmatter validation.

type VersionConfig

type VersionConfig struct {
	Enabled                   bool
	LastVersion               string // version ID that serves the root URL (no prefix)
	PublishLatestAtVersionURL bool
	Versions                  []VersionDef
}

VersionConfig holds versioning settings for a collection (engine-level mirror of config.VersioningConfig to avoid import cycles).

type VersionDef

type VersionDef struct {
	ID       string
	Label    string
	Path     string // URL path segment (defaults to ID)
	Banner   string // "none" / "unmaintained" / "unreleased"
	Redirect string // "same-page" / "root"
}

VersionDef describes one version of a versioned docs collection.

type VersionLink struct {
	ID        string
	Label     string
	URL       string // target URL (peer page or version root, based on redirect strategy)
	Title     string
	IsCurrent bool
	IsLatest  bool   // true if this is the last_version
	Banner    string // "none" / "unmaintained" / "unreleased"
	Redirect  string // "same-page" / "root"
}

VersionLink points to the same page in another version (mirrors TranslationLink).

Jump to

Keyboard shortcuts

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