core

type APIEncoding struct {
	ContentType   string                   // Content-Type for this field
	Headers       map[string]*APIParameter // Headers
	Style         string                   // Serialization style
	Explode       bool                     // Explode parameter
	AllowReserved bool                     // Allow reserved characters
}

type APIEndpoint struct {
	// Identity
	OperationID string // Unique operation ID
	Path        string // URL path (e.g., /users/{id})
	Method      string // HTTP method (GET, POST, etc.)

	// Documentation
	Summary     string   // Short summary
	Description string   // Long description
	Tags        []string // Associated tags
	Deprecated  bool     // Is deprecated

	// Request
	Parameters  []*APIParameter // Path, query, header, cookie params
	RequestBody *APIRequestBody // Request body

	// Responses
	Responses map[string]*APIResponse // Status code -> response

	// Security
	Security []map[string][]string // Security requirements

	// Spec reference
	SpecName string // Parent spec name
}

type APIExample struct {
	Summary     string // Example summary
	Description string // Example description
	Value       any    // Example value
}

type APIMediaType struct {
	Schema   *APISchema              // Schema for this media type
	Example  any                     // Example value
	Examples map[string]*APIExample  // Named examples
	Encoding map[string]*APIEncoding // Encoding for multipart
}

type APIOAuthFlow struct {
	AuthorizationURL string            // Authorization URL
	TokenURL         string            // Token URL
	RefreshURL       string            // Refresh URL
	Scopes           map[string]string // Available scopes (scope -> description)
}

type APIOAuthFlows struct {
	Implicit          *APIOAuthFlow // Implicit flow
	Password          *APIOAuthFlow // Password flow
	ClientCredentials *APIOAuthFlow // Client credentials flow
	AuthorizationCode *APIOAuthFlow // Authorization code flow
}

type APIParameter struct {
	Name        string                 // Parameter name
	In          string                 // Location: path, query, header, cookie
	Description string                 // Parameter description
	Required    bool                   // Is required
	Deprecated  bool                   // Is deprecated
	Schema      *APISchema             // Parameter schema
	Example     any                    // Example value
	Examples    map[string]*APIExample // Named examples
}

type APIPathGroup struct {
	Path      string          // Path segment (e.g., /users)
	Endpoints []*APIEndpoint  // Endpoints at this path
	Children  []*APIPathGroup // Sub-paths
}

type APIRequestBody struct {
	Description string                   // Request body description
	Required    bool                     // Is required
	Content     map[string]*APIMediaType // Media type -> content
}

type APIResponse struct {
	Description string                   // Response description
	Headers     map[string]*APIParameter // Response headers
	Content     map[string]*APIMediaType // Media type -> content
}

type APISchema struct {
	Type        string                // Schema type (string, number, object, array, etc.)
	Format      string                // Format (date-time, email, uuid, etc.)
	Description string                // Schema description
	Properties  map[string]*APISchema // Object properties
	Items       *APISchema            // Array items schema
	Required    []string              // Required properties
	Enum        []any                 // Enumeration values
	Default     any                   // Default value
	Example     any                   // Example value
	Nullable    bool                  // Can be null
	ReadOnly    bool                  // Read-only property
	WriteOnly   bool                  // Write-only property
	Deprecated  bool                  // Is deprecated

	// Validation
	Minimum       *float64 // Minimum value
	Maximum       *float64 // Maximum value
	MinLength     *int     // Minimum string length
	MaxLength     *int     // Maximum string length
	Pattern       string   // Regex pattern
	MinItems      *int     // Minimum array items
	MaxItems      *int     // Maximum array items
	UniqueItems   bool     // Array items must be unique
	MinProperties *int     // Minimum object properties
	MaxProperties *int     // Maximum object properties

	// Composition
	AllOf []APISchema // All of these schemas
	OneOf []APISchema // One of these schemas
	AnyOf []APISchema // Any of these schemas
	Not   *APISchema  // Not this schema

	// Reference
	Ref string // $ref value
}

type APISecurityScheme struct {
	Type             string         // Type: apiKey, http, oauth2, openIdConnect
	Description      string         // Description
	Name             string         // Header/query/cookie name (for apiKey)
	In               string         // Location: header, query, cookie (for apiKey)
	Scheme           string         // Auth scheme: basic, bearer, etc. (for http)
	BearerFormat     string         // Bearer token format (for http bearer)
	Flows            *APIOAuthFlows // OAuth flows (for oauth2)
	OpenIDConnectURL string         // OpenID Connect URL (for openIdConnect)
}

type APIServer struct {
	URL         string                       // Server URL
	Description string                       // Server description
	Variables   map[string]APIServerVariable // Server variables
}

type APIServerVariable struct {
	Default     string   // Default value
	Description string   // Variable description
	Enum        []string // Allowed values
}

type APISpec struct {
	// Metadata
	Name         string    // Spec name (filename or derived from URL)
	Title        string    // API title from spec info.title
	Description  string    // API description from spec info.description
	Version      string    // API version from spec info.version
	FilePath     string    // Local file path (if from file)
	URL          string    // Remote URL (if fetched)
	LastFetched  time.Time // Last fetch time for remote specs
	ETag         string    // ETag for cache validation
	LastModified string    // Last-Modified header for cache validation

	// Specification data
	OpenAPIVersion  string                        // OpenAPI version (3.0.x, 3.1.x)
	Servers         []APIServer                   // API servers
	Endpoints       []*APIEndpoint                // All endpoints/operations
	SecuritySchemes map[string]*APISecurityScheme // Security schemes defined in spec
	Tags            []APITag                      // Tags for organization
	Schemas         map[string]*APISchema         // Reusable schemas from components

	// Organization
	OrganizedByPath []*APIPathGroup // Endpoints organized by path hierarchy
	OrganizedByTag  []*APITagGroup  // Endpoints organized by tags
	FlatEndpoints   []*APIEndpoint  // Flat list for search

	// Output paths
	OutputPath string // Generated HTML file path
}

type APISpecSource struct {
	Type      string // "file" or "url"
	Location  string // File path or URL
	CachePath string // Cache file path for URL sources
}

type APITag struct {
	Name        string // Tag name
	Description string // Tag description
}

type APITagGroup struct {
	Tag       APITag         // Tag info
	Endpoints []*APIEndpoint // Endpoints with this tag
}

type AnalyticsConfig struct {
	Enabled   bool                `yaml:"enabled"`
	Providers []AnalyticsProvider `yaml:"providers"`
}

type AnalyticsProvider struct {
	Type    string         `yaml:"type"` // ga4, plausible, umami, matomo, fathom, simple, custom
	Enabled bool           `yaml:"enabled"`
	Config  map[string]any `yaml:"config"` // Provider-specific configuration
}

type BrokenLink struct {
	Link       CollectedLink
	Reason     string
	Suggestion string // Optional: "did you mean X?"
}

type CTASection struct {
	Title       string            `yaml:"title"`
	Description string            `yaml:"description"`
	Buttons     []HeroButton      `yaml:"buttons"`
	Background  SectionBackground `yaml:"background"`
}

type ChangeCategory struct {
	Type    ChangeType
	Entries []ChangeEntry
}

type ChangeEntry struct {
	Description string // the change description
	RawMD       string // raw markdown
	HTML        string // rendered HTML
}

type ChangeType string

type ChangelogConfig struct {
	Enabled     bool   `yaml:"enabled"`
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	Path        string `yaml:"path"`        // output path (default: "changelog")
	RSSEnabled  bool   `yaml:"rss_enabled"` // generate RSS feed
	Repository  string `yaml:"repository"`  // GitHub repository URL for compare links
}

type ChangelogPage struct {
	Config      ChangelogConfig
	Releases    []Release
	LastUpdated time.Time
}

type ClaudeAssistConfig struct {
	Enabled bool   `yaml:"enabled"` // Enable "Ask Claude" button
	Prompt  string `yaml:"prompt"`  // Custom prompt prefix (optional)
	Label   string `yaml:"label"`   // Button label (default: "Ask Claude")
}

type CollectedLink struct {
	URL        string // The link URL
	SourceFile string // Source markdown file path
	Line       int    // Line number in source file
	Column     int    // Column number
	Text       string // Link text (for context)
	LinkType   LinkType
}

type ComponentStatus string

type ContactConfig struct {
	Enabled     bool          `yaml:"enabled"`
	Title       string        `yaml:"title"`
	Description string        `yaml:"description"`
	Path        string        `yaml:"path"`
	Email       string        `yaml:"email"`
	Info        []ContactInfo `yaml:"info"`
}

type ContactInfo struct {
	Icon string `yaml:"icon"`
	Text string `yaml:"text"`
}

type ContactPage struct {
	Config ContactConfig
}

type FaqCategory struct {
	Name  string    `yaml:"name"`
	Slug  string    `yaml:"-"`
	Order int       `yaml:"order"`
	Items []FaqItem `yaml:"items"`
}

type FaqConfig struct {
	Enabled     bool          `yaml:"enabled"`
	Title       string        `yaml:"title"`
	Description string        `yaml:"description"`
	Path        string        `yaml:"path"`
	Categories  []FaqCategory `yaml:"categories"`
}

type FaqItem struct {
	Question string   `yaml:"question"`
	Answer   string   `yaml:"answer"`
	Slug     string   `yaml:"-"`
	Order    int      `yaml:"order"`
	Tags     []string `yaml:"tags"`

	// For markdown-based items
	AnswerHTML string `yaml:"-"`
	FilePath   string `yaml:"-"`
	Category   string `yaml:"category"`
}

type FaqPage struct {
	Config     FaqConfig
	Categories []FaqCategory
}

type FeatureItem struct {
	Icon        string `yaml:"icon"`
	Emoji       string `yaml:"emoji"`
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
}

type FeaturesSection struct {
	Title      string            `yaml:"title"`
	Items      []FeatureItem     `yaml:"items"`
	Background SectionBackground `yaml:"background"`
}

type FooterBadge struct {
	Text string `yaml:"text"`
	URL  string `yaml:"url"`
}

type FooterConfig struct {
	Copyright   string            `yaml:"copyright"`
	Links       []FooterLinkGroup `yaml:"links"`
	Social      []SocialLink      `yaml:"social"`
	Badges      []FooterBadge     `yaml:"badges"`
	HideVersion bool              `yaml:"hideVersion"`
}

type FooterLink struct {
	Text string `yaml:"text"`
	URL  string `yaml:"url"`
}

type FooterLinkGroup struct {
	Title string       `yaml:"title"`
	Items []FooterLink `yaml:"items"`
}

type HTTPMethod string

type HeroButton struct {
	Text    string `yaml:"text"`
	URL     string `yaml:"url"`
	Primary bool   `yaml:"primary"`
}

type HeroSection struct {
	Title      string            `yaml:"title"`
	Subtitle   string            `yaml:"subtitle"`
	Buttons    []HeroButton      `yaml:"buttons"`
	Image      string            `yaml:"image"`
	Background SectionBackground `yaml:"background"`
}

type I18nConfig struct {
	Enabled           bool           `yaml:"enabled"`
	DefaultLocale     string         `yaml:"default_locale"`      // Default locale code (e.g., "en")
	Locales           []LocaleInfo   `yaml:"locales"`             // Available locales
	Fallback          string         `yaml:"fallback"`            // Fallback locale for missing translations
	HideDefaultLocale bool           `yaml:"hide_default_locale"` // Use /page.html instead of /en/page.html for default
	ShowUntranslated  bool           `yaml:"show_untranslated"`   // Show fallback content with warning badge
	Selector          LocaleSelector `yaml:"selector"`            // UI selector configuration
}

type ImageTextItem struct {
	Icon        string `yaml:"icon"`
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
}

type ImageTextSection struct {
	ID            string            `yaml:"id"` // Section ID for ordering
	Title         string            `yaml:"title"`
	Description   string            `yaml:"description"`
	Content       string            `yaml:"content"`        // Markdown content
	Image         string            `yaml:"image"`          // Image URL
	ImageAlt      string            `yaml:"image_alt"`      // Image alt text
	ImagePosition string            `yaml:"image_position"` // left or right (default: right)
	Items         []ImageTextItem   `yaml:"items"`          // Optional bullet points
	Buttons       []HeroButton      `yaml:"buttons"`        // Optional CTA buttons
	Background    SectionBackground `yaml:"background"`
	Order         int               `yaml:"order"` // Display order
}

type Incident struct {
	// Identity
	ID       string `yaml:"id"` // derived from filename if not set
	Slug     string `yaml:"-"`  // URL-friendly identifier
	FilePath string `yaml:"-"`  // source file path

	// Metadata from frontmatter
	Title              string           `yaml:"title"`
	Status             IncidentStatus   `yaml:"status"`
	Severity           IncidentSeverity `yaml:"severity"`
	AffectedComponents []string         `yaml:"affected_components"`
	CreatedAt          time.Time        `yaml:"created_at"`
	UpdatedAt          time.Time        `yaml:"updated_at"`
	ResolvedAt         *time.Time       `yaml:"resolved_at"`

	// Content
	Updates []IncidentUpdate `yaml:"-"` // parsed from markdown content
	RawMD   string           `yaml:"-"` // raw markdown content
	HTML    string           `yaml:"-"` // rendered HTML

	// Output
	OutputPath string `yaml:"-"` // generated HTML path
}

type IncidentSeverity string

type IncidentStatus string

type IncidentUpdate struct {
	Timestamp time.Time      `yaml:"timestamp"`
	Status    IncidentStatus `yaml:"status"`
	Message   string         `yaml:"message"` // rendered HTML
	RawMD     string         `yaml:"-"`       // raw markdown
}

type KBArticle struct {
	// Identity
	Slug     string `yaml:"-"`
	FilePath string `yaml:"-"`

	// Metadata from frontmatter
	Title       string   `yaml:"title"`
	Description string   `yaml:"description"`
	Tags        []string `yaml:"tags"`
	Order       int      `yaml:"order"`

	// Category
	CategorySlug string `yaml:"-"`
	CategoryName string `yaml:"-"`

	// Content
	RawMD string `yaml:"-"`
	HTML  string `yaml:"-"`

	// Navigation
	Prev *KBArticle `yaml:"-"`
	Next *KBArticle `yaml:"-"`

	// Related
	RelatedArticles []KBArticle `yaml:"-"`

	// Output
	OutputPath string `yaml:"-"`
}

type KBCategory struct {
	// Identity
	Slug string `yaml:"-"`

	// Display
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Icon        string `yaml:"icon"`
	Order       int    `yaml:"order"`

	// Content
	Articles     []KBArticle `yaml:"-"`
	ArticleCount int         `yaml:"-"`

	// Output
	OutputPath string `yaml:"-"`
}

type KBCategoryDef struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Icon        string `yaml:"icon"`
	Order       int    `yaml:"order"`
}

type KBConfig struct {
	Enabled     bool                     `yaml:"enabled"`
	Title       string                   `yaml:"title"`
	Description string                   `yaml:"description"`
	Path        string                   `yaml:"path"`
	Search      KBSearchConfig           `yaml:"search"`
	Categories  map[string]KBCategoryDef `yaml:"categories"` // Override category display names
}

type KBPage struct {
	Config        KBConfig
	Categories    []KBCategory
	Articles      []KBArticle // All articles (flat list for search)
	TotalArticles int
}

type KBSearchConfig struct {
	Enabled     bool   `yaml:"enabled"`
	Placeholder string `yaml:"placeholder"`
}

type LandingConfig struct {
	Enabled      bool                `yaml:"enabled"`
	Nav          []LandingNavLink    `yaml:"nav"`
	Hero         HeroSection         `yaml:"hero"`
	Features     FeaturesSection     `yaml:"features"`
	Steps        StepsSection        `yaml:"steps"`
	CTA          CTASection          `yaml:"cta"`
	Testimonials TestimonialsSection `yaml:"testimonials"`
	OpenSource   OpenSourceSection   `yaml:"opensource"`
	Links        LinksSection        `yaml:"links"`
	ImageText    []ImageTextSection  `yaml:"image_text"`
	TextBlocks   []TextSection       `yaml:"text_blocks"`
	LinksGrid    []LinksGridSection  `yaml:"links_grid"`
}

type LandingNavLink struct {
	Text string `yaml:"text"`
	URL  string `yaml:"url"`
}

type LandingPage struct {
	Config       LandingConfig
	Hero         *HeroSection
	Features     *FeaturesSection
	Steps        *StepsSection
	CTA          *CTASection
	Testimonials *TestimonialsSection
	OpenSource   *OpenSourceSection
	Links        *LinksSection
	ImageText    []*ImageTextSection
	TextBlocks   []*TextSection
	LinksGrid    []*LinksGridSection
}

type LegalConfig struct {
	Enabled     bool   `yaml:"enabled"`
	Path        string `yaml:"path"`
	FooterGroup string `yaml:"footer_group"`
}

type LegalPage struct {
	// Identity
	Slug     string `yaml:"-"`
	FilePath string `yaml:"-"`

	// Metadata from frontmatter
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	Order       int    `yaml:"order"`

	// Content
	RawMD string `yaml:"-"`
	HTML  string `yaml:"-"`

	// Output
	OutputPath string `yaml:"-"`
}

type LinkCheckConfig struct {
	Enabled         bool          `yaml:"enabled"`
	Mode            LinkCheckMode `yaml:"mode"`
	CheckExternal   bool          `yaml:"check_external"`
	ExternalTimeout int           `yaml:"external_timeout"` // Seconds
	IgnorePatterns  []string      `yaml:"ignore_patterns"`  // Glob patterns to skip
	AllowedBroken   []string      `yaml:"allowed_broken"`   // Known broken links to ignore
}

type LinkCheckMode string

type LinkCheckResult struct {
	TotalLinks    int
	BrokenLinks   []BrokenLink
	SkippedLinks  int // Links that matched ignore patterns
	ExternalLinks int // External links (checked or not)
}

type LinkItem struct {
	Icon        string `yaml:"icon"`
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	URL         string `yaml:"url"`
}

type LinkType int

type LinksGridItem struct {
	Icon        string `yaml:"icon"` // Icon identifier or emoji
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	URL         string `yaml:"url"`
	External    bool   `yaml:"external"` // Opens in new tab (default: true for http/https)
}

type LinksGridSection struct {
	ID          string            `yaml:"id"` // Section ID for ordering
	Title       string            `yaml:"title"`
	Description string            `yaml:"description"`
	Columns     int               `yaml:"columns"` // Number of columns (default: 4)
	Items       []LinksGridItem   `yaml:"items"`
	Background  SectionBackground `yaml:"background"`
	Order       int               `yaml:"order"` // Display order
}

type LinksSection struct {
	Title       string     `yaml:"title"`
	Description string     `yaml:"description"`
	Items       []LinkItem `yaml:"items"`
}

type LocaleInfo struct {
	Code      string `yaml:"code"`      // Locale code (e.g., "en", "fr", "de")
	Name      string `yaml:"name"`      // Display name (e.g., "English", "Francais")
	Direction string `yaml:"direction"` // Text direction: "ltr" or "rtl"
	Flag      string `yaml:"flag"`      // Optional flag emoji or icon
}

type LocaleSelector struct {
	Position  string `yaml:"position"`   // "header" or "sidebar"
	ShowFlags bool   `yaml:"show_flags"` // Show flag icons/emojis
}

type LocalizedSite struct {
	Locale     LocaleInfo // Current locale being built
	Pages      []*Page    // Pages for this locale
	OutputRoot string     // Output directory for this locale
}

type MCPConfig struct {
	Enabled   bool     `yaml:"enabled"`
	SpecFiles []string `yaml:"spec_files"` // JSON manifest file paths/globs relative to docs root
	Path      string   `yaml:"path"`       // Output URL path (default: "mcp")
}

type MCPPrompt struct {
	Name        string
	Description string
	Arguments   []*MCPPromptArgument
}

type MCPPromptArgument struct {
	Name        string
	Description string
	Required    bool
}

type MCPResource struct {
	URI         string
	Name        string
	Description string
	MimeType    string
}

type MCPSchema struct {
	Type        string
	Description string
	Properties  map[string]*MCPSchema
	Required    []string
	Enum        []any
	Items       *MCPSchema // for array types
}

type MCPSpec struct {
	Name        string
	Description string
	Slug        string
	Tools       []*MCPTool
	Resources   []*MCPResource
	Prompts     []*MCPPrompt
	OutputPath  string
}

type MCPTool struct {
	Name        string
	Description string
	InputSchema *MCPSchema
}

type MCPToolGroup struct {
	Name  string
	Tools []*MCPTool
}

type Maintenance struct {
	// Identity
	ID       string `yaml:"id"`
	Slug     string `yaml:"-"`
	FilePath string `yaml:"-"`

	// Metadata
	Title              string            `yaml:"title"`
	Description        string            `yaml:"description"`
	AffectedComponents []string          `yaml:"affected_components"`
	ScheduledStart     time.Time         `yaml:"scheduled_start"`
	ScheduledEnd       time.Time         `yaml:"scheduled_end"`
	Status             MaintenanceStatus `yaml:"status"`

	// Content
	RawMD string `yaml:"-"`
	HTML  string `yaml:"-"`

	// Output
	OutputPath string `yaml:"-"`
}

type MaintenanceStatus string

type Metadata struct {
	// Basic metadata
	Title       string   `yaml:"title"`
	Description string   `yaml:"description"`
	Tags        []string `yaml:"tags"`
	Author      string   `yaml:"author"`
	Date        string   `yaml:"date"`

	// Menu/Navigation overrides
	MenuTitle string `yaml:"menu_title"` // Override display name in navigation
	MenuOrder int    `yaml:"menu_order"` // Override order (takes precedence over file numbering)
	Hidden    bool   `yaml:"hidden"`     // Hide from navigation

	// Layout overrides
	FullWidth bool `yaml:"full_width"` // Hide sidebar, use full-width layout
	NoHeader  bool `yaml:"no_header"`  // Hide page header (title, buttons, description)
	NoWidgets bool `yaml:"no_widgets"` // Hide feedback and newsletter widgets

	// SEO metadata
	SEO SEO `yaml:"seo"`

	// OpenAPI integration
	OpenAPISpec   string `yaml:"openapi_spec"`   // Reference to OpenAPI spec file/URL
	OpenAPIPath   string `yaml:"openapi_path"`   // Specific endpoint path to embed
	OpenAPIMethod string `yaml:"openapi_method"` // Specific HTTP method to embed

	// Stale warning overrides
	StaleWarning       *bool `yaml:"stale_warning"`        // Override site setting (nil = use site default)
	StaleThresholdDays *int  `yaml:"stale_threshold_days"` // Override threshold (nil = use site default)

	// Portfolio-specific fields
	Image    string         `yaml:"image"`    // Project image
	Links    []MetadataLink `yaml:"links"`    // Project links
	Featured bool           `yaml:"featured"` // Featured project

	// FAQ-specific fields
	Question string `yaml:"question"` // FAQ question text
	Category string `yaml:"category"` // FAQ category name

	// Version-specific fields
	Versions     []string `yaml:"versions"`      // Versions this page appears in (empty = all)
	Since        string   `yaml:"since"`         // Version this feature was introduced
	DeprecatedIn string   `yaml:"deprecated_in"` // Version where feature was deprecated
	RemovedIn    string   `yaml:"removed_in"`    // Version where feature was removed
	VersionNote  string   `yaml:"version_note"`  // Version to show note for

	// Custom fields (for extensibility)
	Custom map[string]any `yaml:"custom"`
}

type MetadataLink struct {
	Text string `yaml:"text"`
	URL  string `yaml:"url"`
}

type NavItem struct {
	Title      string     // Display title
	Path       string     // URL path
	Order      int        // Sort order
	Active     bool       // Is current page
	IsExternal bool       // True if external URL (opens in new tab)
	Children   []*NavItem // Nested items
	Page       *Page      // Associated page
}

type Navigation struct {
	Items []*NavItem
}

type OpenAPIConfig struct {
	Enabled           bool     // Enable OpenAPI support
	SpecFiles         []string // Local spec file paths/globs
	SpecURLs          []string // Remote spec URLs to fetch
	DefaultView       string   // Default organization view: "path", "tag", "flat"
	SyncOnBuild       bool     // Sync remote specs on every build
	CacheDir          string   // Cache directory for remote specs
	EnableTesting     bool     // Enable API testing UI
	EnableExport      bool     // Enable export to restcli/curl
	EnableCodeSamples bool     // Enable code samples (curl, fetch, Go, Python)
	LazyLoadChunkSize int      // Chunk size for lazy loading (bytes)
}

type OpenSourceSection struct {
	Title       string            `yaml:"title"`
	Description string            `yaml:"description"`
	Links       []SimpleLink      `yaml:"links"`
	Background  SectionBackground `yaml:"background"`
}

type PDFExportConfig struct {
	Enabled        bool `yaml:"enabled"`          // Enable PDF export button
	PageBreakLevel int  `yaml:"page_break_level"` // Heading level for page breaks (1=h1, 2=h1+h2, 0=none)
}

type Page struct {
	// File information
	SourcePath string    // Original markdown file path
	RelPath    string    // Relative path from docs root
	Slug       string    // URL-friendly slug (e.g., "getting-started")
	OutputPath string    // Output HTML file path
	ModTime    time.Time // File modification time

	// Content
	Metadata Metadata // Parsed frontmatter
	RawMD    []byte   // Raw markdown content (without frontmatter)
	HTML     []byte   // Rendered HTML content

	// Navigation
	Order    int     // Computed order (from filename prefix or metadata)
	Parent   *Page   // Parent page (for nested navigation)
	Children []*Page // Child pages
	Next     *Page   // Next page in sequence
	Prev     *Page   // Previous page in sequence

	// Table of Contents
	TOC *TOC // Parsed table of contents from headings

	// Stale content warning (computed at build time)
	IsStale         bool   // True if content is older than threshold
	StaleAge        string // Human-readable age: "2 years", "18 months"
	DaysSinceUpdate int    // Exact days since last update
}

type ParameterLocation string

type PortfolioConfig struct {
	Enabled     bool   `yaml:"enabled"`
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	Path        string `yaml:"path"`
}

type PortfolioPage struct {
	Config           PortfolioConfig
	Projects         []Project
	FeaturedProjects []Project
	Tags             []string // All unique tags for filtering
}

type Project struct {
	// Identity
	ID       string `yaml:"-"`
	Slug     string `yaml:"-"`
	FilePath string `yaml:"-"`

	// Metadata from frontmatter
	Title       string       `yaml:"title"`
	Description string       `yaml:"description"`
	Image       string       `yaml:"image"`
	Tags        []string     `yaml:"tags"`
	Links       []SimpleLink `yaml:"links"`
	Date        time.Time    `yaml:"date"`
	Featured    bool         `yaml:"featured"`
	Order       int          `yaml:"order"`

	// Content
	RawMD string `yaml:"-"`
	HTML  string `yaml:"-"`

	// Output
	OutputPath string `yaml:"-"`
}

type Release struct {
	// Identity
	Version string `yaml:"version"`
	Slug    string `yaml:"-"` // URL-friendly version (e.g., "1.2.0")

	// Metadata from frontmatter
	Date       time.Time `yaml:"date"`
	Title      string    `yaml:"title"`      // optional title for the release
	Prerelease bool      `yaml:"prerelease"` // is this a prerelease version

	// Semantic version components (for sorting)
	Major int `yaml:"-"`
	Minor int `yaml:"-"`
	Patch int `yaml:"-"`

	// Content
	Categories []ChangeCategory `yaml:"-"` // changes grouped by category
	RawMD      string           `yaml:"-"` // raw markdown content
	HTML       string           `yaml:"-"` // rendered HTML

	// Generated
	CompareURL string `yaml:"-"` // GitHub compare link to previous version
	OutputPath string `yaml:"-"` // generated HTML path
}

type RoadmapColumn struct {
	ID    string `yaml:"id"`
	Label string `yaml:"label"`
}

type RoadmapConfig struct {
	Enabled      bool            `yaml:"enabled"`
	Title        string          `yaml:"title"`
	Description  string          `yaml:"description"`
	Layout       string          `yaml:"layout"` // "board" or "timeline"
	ShowVersions bool            `yaml:"show_versions"`
	Path         string          `yaml:"path"`
	Columns      []RoadmapColumn `yaml:"columns"`
	Items        []RoadmapItem   `yaml:"items"`
}

type RoadmapItem struct {
	Title        string   `yaml:"title"`
	Description  string   `yaml:"description"`
	Status       string   `yaml:"status"`
	Version      string   `yaml:"version"`
	Tags         []string `yaml:"tags"`
	ShippedDate  string   `yaml:"shipped_date"`
	ChangelogURL string   `yaml:"changelog_url"`
}

type RoadmapPage struct {
	Config RoadmapConfig
}

type SEO struct {
	Title       string   `yaml:"title"`       // SEO title (og:title)
	Description string   `yaml:"description"` // SEO description (og:description)
	Keywords    []string `yaml:"keywords"`    // Meta keywords
	Image       string   `yaml:"image"`       // og:image
	Author      string   `yaml:"author"`      // Author
	Canonical   string   `yaml:"canonical"`   // Canonical URL
	NoIndex     bool     `yaml:"noindex"`     // Don't index this page
	NoFollow    bool     `yaml:"nofollow"`    // Don't follow links on this page
}

type SLAStats struct {
	Target     float64 `json:"target"`      // target SLA (e.g., 99.9)
	Current7d  float64 `json:"current_7d"`  // uptime % over last 7 days
	Current30d float64 `json:"current_30d"` // uptime % over last 30 days
	Current90d float64 `json:"current_90d"` // uptime % over last 90 days
}

type SchemaType string

type SectionBackground struct {
	Image      string `yaml:"image"`      // Background image URL
	Overlay    string `yaml:"overlay"`    // Overlay color (e.g., "rgba(0,0,0,0.6)")
	Color      string `yaml:"color"`      // Background color
	Position   string `yaml:"position"`   // Background position (default: "center")
	Size       string `yaml:"size"`       // Background size (default: "cover")
	Attachment string `yaml:"attachment"` // Background attachment (scroll/fixed)
}

type SecuritySchemeType string

type SimpleLink struct {
	Text string `yaml:"text"`
	URL  string `yaml:"url"`
}

type Site struct {
	// Configuration
	Config SiteConfig

	// Content
	Pages         []*Page        // All pages
	RootPages     []*Page        // Top-level pages (for navigation)
	Navigation    *Navigation    // Site navigation tree
	APISpecs      []*APISpec     // OpenAPI specifications
	StatusPage    *StatusPage    // Status page data (if enabled)
	ChangelogPage *ChangelogPage // Changelog data (if enabled)
	LandingPage   *LandingPage   // Landing page data (if enabled)
	PortfolioPage *PortfolioPage // Portfolio page data (if enabled)
	ContactPage   *ContactPage   // Contact page data (if enabled)
	FaqPage       *FaqPage       // FAQ page data (if enabled)
	LegalPages    []*LegalPage   // Legal pages (if enabled)
	KBPage        *KBPage        // Knowledge Base data (if enabled)
	WaitlistPage  *WaitlistPage  // Waitlist page data (if enabled)
	RoadmapPage   *RoadmapPage   // Roadmap page data (if enabled)
	MCPSpecs      []*MCPSpec     // MCP server documentation (if enabled)

	// Versioning
	VersionedPages map[string][]*Page // Pages per version (key = version name)
	CurrentVersion string             // Current version being built (empty = default)

	// Internationalization
	LocalizedPages map[string][]*Page // Pages per locale (key = locale code)
	CurrentLocale  string             // Current locale being built (empty = default)

	// Paths
	DocsRoot   string // Root directory of markdown files
	OutputRoot string // Output directory for generated site
}

type SiteConfig struct {
	// Basic info
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	BaseURL     string `yaml:"base_url"`
	Author      string `yaml:"author"`

	// Theme
	Theme       string      `yaml:"theme"`        // Theme name (default: "default")
	DarkMode    bool        `yaml:"dark_mode"`    // Enable dark mode by default
	ThemeConfig ThemeConfig `yaml:"theme_config"` // Custom theme configuration

	// Features
	EnableLLMS   bool `yaml:"enable_llms"`   // Generate llms.txt
	EnableSearch bool `yaml:"enable_search"` // Enable search (future)

	// Entrypoint
	Entrypoint     string `yaml:"entrypoint"` // Custom homepage file (default: index.md)
	SingleFileMode bool   `yaml:"-"`          // Only process the entrypoint file

	// Navigation
	NavDepth int `yaml:"nav_depth"` // Max depth for navigation tree (0 = unlimited)

	// Output
	CleanURLs bool `yaml:"clean_urls"` // Use /page/ instead of /page.html

	// OpenAPI
	OpenAPI OpenAPIConfig `yaml:"openapi"` // OpenAPI/Swagger configuration

	// Status
	Status StatusConfig `yaml:"status"` // Status page configuration

	// Changelog
	Changelog ChangelogConfig `yaml:"changelog"` // Changelog configuration

	// Stale Warning
	StaleWarning StaleWarningConfig `yaml:"stale_warning"` // Stale content warning configuration

	// Landing Page
	Landing LandingConfig `yaml:"landing"` // Landing page configuration

	// Portfolio
	Portfolio PortfolioConfig `yaml:"portfolio"` // Portfolio page configuration

	// Contact
	Contact ContactConfig `yaml:"contact"` // Contact page configuration

	// FAQ
	Faq FaqConfig `yaml:"faq"` // FAQ page configuration

	// Legal
	Legal LegalConfig `yaml:"legal"` // Legal pages configuration

	// Knowledge Base
	KnowledgeBase KBConfig `yaml:"knowledgebase"` // Knowledge Base configuration

	// Waitlist
	Waitlist WaitlistConfig `yaml:"waitlist"` // Waitlist landing page configuration

	// Roadmap
	Roadmap RoadmapConfig `yaml:"roadmap"` // Roadmap page configuration

	// Footer (for landing pages)
	Footer FooterConfig `yaml:"footer"` // Footer configuration

	// Social Links
	SocialLinks []SocialLink `yaml:"social_links"` // Social media links in sidebar

	// Link Check
	LinkCheck LinkCheckConfig `yaml:"link_check"` // Link checker configuration

	// Versions
	Versions VersionConfig `yaml:"versions"` // Multi-version documentation configuration

	// Internationalization
	I18n I18nConfig `yaml:"i18n"` // Internationalization configuration

	// PDF Export
	PDFExport PDFExportConfig `yaml:"pdf_export"` // PDF export configuration

	// Claude Assist
	ClaudeAssist ClaudeAssistConfig `yaml:"claude_assist"` // Claude AI assist configuration

	// Analytics
	Analytics AnalyticsConfig `yaml:"analytics"` // Analytics providers configuration

	// MCP Server Documentation
	MCP MCPConfig `yaml:"mcp"` // MCP server documentation configuration

	// Custom
	Custom map[string]any `yaml:"custom"`
}

type SocialLink struct {
	Name string `yaml:"name"` // Display name (e.g., "GitHub", "Twitter")
	URL  string `yaml:"url"`  // Link URL
	Icon string `yaml:"icon"` // Icon identifier (github, twitter, linkedin, etc.)
}

type StaleWarningConfig struct {
	Enabled        bool   `yaml:"enabled"`
	ThresholdDays  int    `yaml:"threshold_days"`   // Days before content is considered stale
	Message        string `yaml:"message"`          // Custom message (optional)
	ShowUpdateDate bool   `yaml:"show_update_date"` // Show the actual last update date
}

type StatusComponent struct {
	ID          string          `yaml:"id"`
	Name        string          `yaml:"name"`
	Description string          `yaml:"description"`
	Status      ComponentStatus `yaml:"status"`
	Group       string          `yaml:"group"` // optional grouping
	Order       int             `yaml:"order"` // display order within group
	URL         string          `yaml:"url"`   // optional link to service

	// Health check configuration (for external monitoring tools)
	HealthEndpoint string `yaml:"health_endpoint"` // endpoint to check (e.g., /health)
	HealthInterval int    `yaml:"health_interval"` // check interval in seconds (0 = disabled)

	// Uptime tracking configuration
	Uptime UptimeConfig `yaml:"uptime"`

	// Computed uptime data (populated at build time for mode: incidents)
	UptimeData *UptimeData `yaml:"-" json:"uptime_data,omitempty"`
}

type StatusConfig struct {
	Enabled       bool   `yaml:"enabled"`
	Title         string `yaml:"title"`
	Description   string `yaml:"description"`
	Path          string `yaml:"path"`           // output path (default: "status")
	ShowHistory   bool   `yaml:"show_history"`   // show incident history
	HistoryMonths int    `yaml:"history_months"` // months of history to show (default: 12)
	RSSEnabled    bool   `yaml:"rss_enabled"`    // generate RSS feed
}

type StatusPage struct {
	Config               StatusConfig
	Components           []StatusComponent
	ComponentGroups      map[string][]StatusComponent // grouped by Group field
	ActiveIncidents      []Incident
	ResolvedIncidents    []Incident
	ScheduledMaintenance []Maintenance
	ActiveMaintenance    []Maintenance
	OverallStatus        ComponentStatus
	LastUpdated          time.Time
	HistoryByMonth       map[string][]Incident // "2025-01" -> incidents
}

type StepItem struct {
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
	Code        string `yaml:"code"`
}

type StepsSection struct {
	Title      string            `yaml:"title"`
	Items      []StepItem        `yaml:"items"`
	Background SectionBackground `yaml:"background"`
}

type TOC struct {
	Items []*TOCItem
}

type TOCItem struct {
	ID       string     // Anchor ID (e.g., "getting-started")
	Title    string     // Heading text
	Level    int        // Heading level (1-6)
	Children []*TOCItem // Nested headings
}

type Testimonial struct {
	Quote  string `yaml:"quote"`
	Author string `yaml:"author"`
	Role   string `yaml:"role"`
	Avatar string `yaml:"avatar"`
}

type TestimonialsSection struct {
	Title      string            `yaml:"title"`
	Items      []Testimonial     `yaml:"items"`
	Background SectionBackground `yaml:"background"`
}

type TextSection struct {
	ID         string            `yaml:"id"` // Section ID for ordering
	Title      string            `yaml:"title"`
	Subtitle   string            `yaml:"subtitle"`
	Content    string            `yaml:"content"`   // Markdown content
	Alignment  string            `yaml:"alignment"` // left, center, right (default: center)
	MaxWidth   string            `yaml:"max_width"` // Max width (e.g., "800px")
	Buttons    []HeroButton      `yaml:"buttons"`   // Optional CTA buttons
	Background SectionBackground `yaml:"background"`
	Order      int               `yaml:"order"` // Display order
}

type ThemeColorSet struct {
	// Backgrounds
	BgPrimary   string `yaml:"bg_primary"`
	BgSecondary string `yaml:"bg_secondary"`
	BgTertiary  string `yaml:"bg_tertiary"`
	BgCode      string `yaml:"bg_code"`
	BgHover     string `yaml:"bg_hover"`

	// Text
	TextPrimary   string `yaml:"text_primary"`
	TextSecondary string `yaml:"text_secondary"`
	TextTertiary  string `yaml:"text_tertiary"`
	TextMuted     string `yaml:"text_muted"`

	// Borders
	BorderPrimary   string `yaml:"border_primary"`
	BorderSecondary string `yaml:"border_secondary"`

	// Accents
	AccentPrimary string `yaml:"accent_primary"`
	AccentHover   string `yaml:"accent_hover"`

	// Links
	LinkColor string `yaml:"link_color"`
	LinkHover string `yaml:"link_hover"`

	// Status colors
	ColorSuccess string `yaml:"color_success"`
	ColorWarning string `yaml:"color_warning"`
	ColorDanger  string `yaml:"color_danger"`
	ColorInfo    string `yaml:"color_info"`
}

type ThemeColors struct {
	// Light mode colors
	Light ThemeColorSet `yaml:"light"`
	// Dark mode colors
	Dark ThemeColorSet `yaml:"dark"`
}

type ThemeConfig struct {
	Name   string      `yaml:"name"`   // Theme name: "default", "dark", or custom
	Colors ThemeColors `yaml:"colors"` // Custom color overrides
	Fonts  ThemeFonts  `yaml:"fonts"`  // Custom font settings
	Hero   ThemeHero   `yaml:"hero"`   // Hero section styling
}

type ThemeFonts struct {
	Heading   string `yaml:"heading"`    // Font family for headings
	Body      string `yaml:"body"`       // Font family for body text
	Code      string `yaml:"code"`       // Font family for code
	GoogleURL string `yaml:"google_url"` // Google Fonts import URL
}

type ThemeHero struct {
	BackgroundImage   string `yaml:"background_image"`   // Background image URL
	BackgroundOverlay string `yaml:"background_overlay"` // Overlay color (e.g., "rgba(0,0,0,0.6)")
	TextAlign         string `yaml:"text_align"`         // Text alignment: left, center, right
	MinHeight         string `yaml:"min_height"`         // Minimum height (e.g., "80vh")
}

type UptimeConfig struct {
	Mode       string  `yaml:"mode" json:"mode"`               // "api" or "incidents"
	Endpoint   string  `yaml:"endpoint" json:"endpoint"`       // API endpoint (for mode: api)
	SLATarget  float64 `yaml:"sla_target" json:"sla_target"`   // target SLA percentage (e.g., 99.9)
	PeriodDays int     `yaml:"period_days" json:"period_days"` // history period in days (default: 90)
}

type UptimeData struct {
	Mode          string      `json:"mode"`           // "api" or "incidents"
	PeriodDays    int         `json:"period_days"`    // number of days in history
	UptimePercent float64     `json:"uptime_percent"` // overall uptime percentage
	History       []UptimeDay `json:"history"`        // daily history (newest first)
	SLA           SLAStats    `json:"sla"`            // SLA statistics
}

type UptimeDay struct {
	Date            string `json:"date"`             // "2025-01-28" format
	Status          string `json:"status"`           // operational, degraded, partial_outage, major_outage, maintenance
	DowntimeMinutes int    `json:"downtime_minutes"` // total downtime in minutes for this day
}

type VersionConfig struct {
	Enabled  bool            `yaml:"enabled"`
	Default  string          `yaml:"default"`  // Default version slug (e.g., "v2")
	List     []VersionInfo   `yaml:"list"`     // Available versions
	Selector VersionSelector `yaml:"selector"` // UI selector configuration
}

type VersionInfo struct {
	Name  string `yaml:"name"`  // Version identifier (e.g., "v2")
	Label string `yaml:"label"` // Display label (e.g., "2.x (Latest)")
	Path  string `yaml:"path"`  // URL path prefix (e.g., "v2")
	EOL   string `yaml:"eol"`   // End of life date (YYYY-MM-DD), empty if still supported
}

type VersionSelector struct {
	Position       string `yaml:"position"`         // "header" or "sidebar"
	ShowEOLWarning bool   `yaml:"show_eol_warning"` // Show warning badge for EOL versions
}

type VersionedSite struct {
	Version    VersionInfo // Current version being built
	Pages      []*Page     // Pages for this version
	OutputRoot string      // Output directory for this version
}

type WaitlistConfig struct {
	Enabled            bool                 `yaml:"enabled"`
	Title              string               `yaml:"title"`
	Tagline            string               `yaml:"tagline"`
	NewsletterEndpoint string               `yaml:"newsletter_endpoint"`
	SiteID             string               `yaml:"site_id"`
	SuccessMessage     string               `yaml:"success_message"`
	SocialLinks        []WaitlistSocialLink `yaml:"social_links"`
	PrivacyURL         string               `yaml:"privacy_url"`
}

type WaitlistPage struct {
	Config WaitlistConfig
}

type WaitlistSocialLink struct {
	Name string `yaml:"name"` // Platform name (github, twitter, discord, etc.)
	URL  string `yaml:"url"`  // Link URL
}