engine

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

type BadgeVariant string

type BreadcrumbItem struct {
	Label   string
	URL     string
	Current bool
}

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

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

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
}

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"`
}

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

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"

	// 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"`
}

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"`
}

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"`
}

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"`
}

type CollectedLink struct {
	Href    string
	IsImage bool
}

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
}

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
}

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

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

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
}

type EditURLValue struct {
	Disabled  bool
	CustomURL string
}

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
}

type FlexDate struct {
	time.Time
}

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"`
	Cascade            map[string]any `yaml:"cascade"`
	Params             map[string]any `yaml:"params"`
	LearningObjectives []string       `yaml:"learning_objectives"`
}

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"`
}

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"`
}

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"`
}

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

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

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"`
}

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

type GlobalNav struct {
	Items []GlobalNavItem
}

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

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

type Heading struct {
	Level int
	ID    string
	Text  string
}

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"`
}

type HeroCTAData struct {
	Label string
	URL   string
}

type HeroCodeData struct {
	Title    string
	Language string
	Body     string
}

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

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

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

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

type HeroStatData struct {
	Value string
	Label string
}

type HomepageData struct {
	Template string
	Hero     HeroData
}

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

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

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

type LayoutType string

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
}

type LogoImage struct {
	URL    string
	Width  int
	Height int
}

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

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
}

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

type NavTree struct {
	Root       *NavNode
	Flat       []*NavNode
	TotalPages int
	MaxDepth   int
	Hash       string
}

type NodeKind string

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

	ShowTags *bool

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

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
}

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
}

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

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
}

type PageMeta struct {
	Draft       bool
	Description string
	Image       string
}

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

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

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

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

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

type PaginationLink struct {
	URL   string
	Title string
}

type PaginationLinks struct {
	Prev *PaginationLink
	Next *PaginationLink
}

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
}

type PhaseTiming struct {
	Phase    string
	Duration time.Duration
}

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

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

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

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

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
}

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

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

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

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

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

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

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
}

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
}

type SiteContext struct {
	Title            string
	BaseURL          string
	BasePath         string // normalized: "/docs/" or "/"
	SiteID           string
	Language         string
	Generator        string
	Favicon          string
	FaviconType      string
	Logo             LogoContext
	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)
}

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

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

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

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
}

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

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
}

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
}

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
}

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
}

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

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

type VersionConfig struct {
	Enabled                   bool
	LastVersion               string // version ID that serves the root URL (no prefix)
	PublishLatestAtVersionURL bool
	Versions                  []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"
}

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"
}