collection

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyCascade 

func ApplyCascade(pages []*engine.Page)

ApplyCascade resolves frontmatter inheritance from section _index.md pages. Each section's `cascade` map is applied to all descendant pages that don't explicitly set those fields. Must be called after BuildSectionTree.

func ApplySidebarFile added in v1.0.0 

func ApplySidebarFile(cfg *engine.CollectionConfig, entry *config.SidebarCollectionEntry) *engine.CollectionConfig

ApplySidebarFile overlays one collection's sidebar.yaml entry onto its resolved config. sidebar.yaml wins over sarde.yaml and frontmatter per the documented precedence chain. Returns a new CollectionConfig (never mutates the input) so it composes after MergeCollectionConfig. entry may be nil.

func BuildCollections 

func BuildCollections(
	files []content.ContentFile,
	siteCfg *config.SiteConfig,
	contentDir string,
) (map[string]*engine.Collection, []engine.ValidationWarning, error)

BuildCollections groups discovered files into typed collections, builds Pages, applies sorting, section trees, draft filtering, and prev/next wiring. Returns the collections map and any validation warnings.

func BuildCollectionsWithOptions 

func BuildCollectionsWithOptions(
	files []content.ContentFile,
	siteCfg *config.SiteConfig,
	contentDir string,
	opts BuildOptions,
) (map[string]*engine.Collection, []engine.ValidationWarning, error)

BuildCollectionsWithOptions groups discovered files into typed collections with optional parallel parsing.

func BuildCompositeNavTrees 

func BuildCompositeNavTrees(col *engine.Collection, langs []string) map[string]*engine.NavTree

BuildCompositeNavTrees builds one NavTree per (lang, version) pair found in the collection's pages. Keyed by LangVersionKey. Used for versioned collections that may also be multi-language.

func BuildCompositeTabSets 

func BuildCompositeTabSets(col *engine.Collection, contentDir string, langs []string) map[string][]*engine.DocsTab

BuildCompositeTabSets builds one tab set per (lang, version) pair found in the collection's pages. Used for collections with both versioning and tabs.

func BuildLabsNav added in v1.0.0 

func BuildLabsNav(col *engine.Collection)

BuildLabsNav builds lab-scoped sidebar trees and wires prev/next navigation within each lab. Supports both 2-level (labs directly under collection root) and 3-level (courses containing labs) structures.

func BuildSectionTree 

func BuildSectionTree(pages []*engine.Page, collectionName string) []*engine.Section

BuildSectionTree constructs a tree of Section nodes from pages. Pages with Kind==KindSection become section index pages. Other pages are assigned to their deepest matching section. Returns top-level sections for the collection.

func BuildSinglePage 

func BuildSinglePage(
	cf content.ContentFile,
	contentDir string,
	collCfg *engine.CollectionConfig,
	schema *engine.FrontmatterSchema,
	summaryLength int,
	lastUpdatedStrategy string,
	taxCfg map[string]config.TaxonomyConfig,
) (*engine.Page, []engine.ValidationWarning, error)

BuildSinglePage parses, infers, and transforms a single ContentFile into a Page. Used by incremental rebuild to re-parse a changed file without rebuilding all collections.

func BuildStandalonePages 

func BuildStandalonePages(
	files []content.ContentFile,
	contentDir string,
	summaryLength int,
	lastUpdatedStrategy string,
) ([]*engine.Page, error)

BuildStandalonePages builds Page objects for root-level files (home, standalone).

func BuildStandalonePagesWithOptions 

func BuildStandalonePagesWithOptions(
	files []content.ContentFile,
	contentDir string,
	summaryLength int,
	lastUpdatedStrategy string,
	opts BuildOptions,
) ([]*engine.Page, error)

BuildStandalonePagesWithOptions builds root-level pages with optional parallel parsing.

func BuildTabs 

func BuildTabs(col *engine.Collection, contentDir string) []*engine.DocsTab

BuildTabs creates DocsTab entries for a tabbed collection (single language).

func BuildTabsI18n 

func BuildTabsI18n(col *engine.Collection, contentDir string, langs []string) []*engine.DocsTab

BuildTabsI18n creates DocsTab entries with per-language nav trees.

func CollectSidebarOverrideWarnings added in v1.0.0 

func CollectSidebarOverrideWarnings(collections map[string]*engine.Collection) []engine.ValidationWarning

CollectSidebarOverrideWarnings scans every collection's resolved sidebar config for sidebar.yaml override and tab keys that no lane's tree-building pass consulted, returning one warning per unmatched key.

Call exactly once per build, after every nav tree has been built, including the i18n-fallback rebuild (RebuildNavTreesWithFallbacks). Computing this earlier would false-positive on keys only matched in fallback-generated lanes.

func DetectTabs 

func DetectTabs(col *engine.Collection) bool

DetectTabs determines whether a collection should use tabbed docs mode. Returns true when: explicit config forces it, or auto-detection finds 2+ top-level sections all with _index.md and no loose root pages.

func FindTabForPage 

func FindTabForPage(tabs []*engine.DocsTab, page *engine.Page) *engine.DocsTab

FindTabForPage returns the tab that contains the given page, or nil.

func InferCollection 

func InferCollection(dirName string) *engine.CollectionConfig

InferCollection returns a CollectionConfig with sensible defaults based on the directory name convention.

func IsBlogName 

func IsBlogName(name string) bool

IsBlogName returns true if the directory name maps to a blog-type collection.

func IsLabsName added in v1.0.0 

func IsLabsName(name string) bool

IsLabsName returns true if the directory name maps to a labs-type collection.

func IsSlidesName added in v1.0.0 

func IsSlidesName(name string) bool

IsSlidesName returns true if the directory name maps to a slides-type collection.

func LangVersionKey 

func LangVersionKey(lang, ver string) string

LangVersionKey computes the composite map key for a (lang, version) pair.

func LinkVersions 

func LinkVersions(pages []*engine.Page)

LinkVersions groups pages across versions by their VersionRelPath and populates each page's VersionPeers slice, mirroring i18n.LinkTranslations.

func MergeCollectionConfig 

func MergeCollectionConfig(inferred *engine.CollectionConfig, siteCfg *config.CollectionSiteConfig) *engine.CollectionConfig

MergeCollectionConfig overlays sarde.yaml collection values onto inferred defaults. Non-zero/non-nil site config values win over inferred values. Returns a new CollectionConfig (does not mutate the input).

func RebuildNavTreesWithFallbacks 

func RebuildNavTreesWithFallbacks(collections map[string]*engine.Collection, allPages []*engine.Page, langs []string, contentDir string)

RebuildNavTreesWithFallbacks rebuilds per-language nav trees after fallback pages have been generated, so every language gets a complete sidebar (real translations + fallback pages from the default language). contentDir must be the real content directory so per-tab nav.yaml files are honored on the rebuild exactly as in the initial build.

func SortPages 

func SortPages(pages []*engine.Page, sortBy, sortOrder string)

SortPages sorts pages in-place by the given key and order. Supported keys: "date", "order", "title", "slug". Order: "asc" or "desc" (defaults to "asc"). Uses stable sort to preserve filesystem order for ties.

func WirePrevNext 

func WirePrevNext(pages []*engine.Page)

Types

type BuildOptions 

type BuildOptions struct {
	Parallel    bool
	WorkerCount int
}

BuildOptions controls content parsing work inside collection builders.

type EffectiveCollection added in v1.0.0 

type EffectiveCollection struct {
	Name         string             `json:"name"`
	InferredType string             `json:"inferredType"` // "blog" | "docs" | "default"
	SortBy       FieldValue         `json:"sortBy"`
	SortOrder    FieldValue         `json:"sortOrder"`
	Layout       FieldValue         `json:"layout"`
	Permalink    FieldValue         `json:"permalink"`
	Paginate     FieldValue         `json:"paginate"`
	Feed         FieldValue         `json:"feed"`
	Tabs         FieldValue         `json:"tabs"` // value: bool | null (null = auto-detect)
	Sidebar      *EffectiveSidebar  `json:"sidebar"`
	TOC          *EffectiveTOC      `json:"toc"`
	PrevNext     *EffectivePrevNext `json:"prevNext"`
}

EffectiveCollection is one collection's fully resolved config plus per-field provenance. Scope is limited to fields that flow through InferCollection/MergeCollectionConfig.

func BuildEffectiveConfig added in v1.0.0 

func BuildEffectiveConfig(projectDir string) ([]EffectiveCollection, error)

BuildEffectiveConfig computes the merged per-collection config and each field's provenance for every collection in projectDir. It re-resolves sarde.yaml fresh on every call so callers always see the file's current state — the Studio bridge must not cache this either.

Excluded from the report entirely: Enabled/Path/URLPrefix/I18nFallback (InferCollection never sets them, so there is no inferred-vs-explicit story), Versioning (always explicit opt-in, never inferred), TOC.MinLevel and Sidebar.CollapseLevel (no sarde.yaml field / not edited in Studio), and sidebar.yaml path overrides (a different file entirely).

PROVENANCE CAVEAT: cfg.Collections and cfg.Permalinks (from config.Resolve) are used both as MergeCollectionConfig's input AND as the "was this explicitly set in sarde.yaml" signal. That is valid only because nothing in today's 5-layer cascade other than sarde.yaml (layer 3) populates SiteConfig.Collections/Permalinks: Defaults() sets neither, ResolveOptions.ThemeDir is never set by any caller in this repo, and CLI flags/env (layers 4-5) never touch collections. If a future change starts merging theme.yaml collection settings, these "sarde_yaml" labels would silently cover theme.yaml too — switch provenance to a separate, isolated config.LoadFile(configPath) call if that happens.

type EffectivePrevNext added in v1.0.0 

type EffectivePrevNext struct {
	Enabled FieldValue `json:"enabled"`
	Labels  FieldValue `json:"labels"` // value: [2]string
}

EffectivePrevNext mirrors engine.PrevNextConfig.

type EffectiveSidebar added in v1.0.0 

type EffectiveSidebar struct {
	Collapsible        FieldValue `json:"collapsible"`
	CollapsedByDefault FieldValue `json:"collapsedByDefault"`
	MaxDepth           FieldValue `json:"maxDepth"`
	Search             FieldValue `json:"search"`
}

EffectiveSidebar mirrors the subset of engine.SidebarConfig that Sarde Studio's collection settings expose. CollapseLevel and sidebar.yaml path overrides are intentionally out of scope (see BuildEffectiveConfig).

type EffectiveTOC added in v1.0.0 

type EffectiveTOC struct {
	Enabled         FieldValue `json:"enabled"`
	ScrollHighlight FieldValue `json:"scrollHighlight"`
	Depth           FieldValue `json:"depth"` // engine.TOCConfig.MaxLevel
}

EffectiveTOC mirrors the subset of engine.TOCConfig Studio exposes. MinLevel has no sarde.yaml field (always inference-only), so it is omitted.

type FieldSource added in v1.0.0 

type FieldSource string

FieldSource identifies where an effective collection config value came from: the zero-config, directory-name-based inference in InferCollection, or an explicit override in the user's sarde.yaml. 

const (
	SourceInferred  FieldSource = "inferred"
	SourceSardeYAML FieldSource = "sarde_yaml"
)

type FieldValue added in v1.0.0 

type FieldValue struct {
	Value  any         `json:"value"`
	Source FieldSource `json:"source"`
}

FieldValue pairs an effective (merged) value with its provenance.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.