Documentation
¶
Overview ¶
Package nav implements the filesystem walker, nav tree builder, and core data types used throughout kwelea.
The primary entry point is NewSite, which reads a config.Config, walks the docs directory (or follows the manual [nav] order defined in kwelea.toml), parses YAML-style frontmatter from every Markdown file, strips numeric filename prefixes, derives URL slugs, and returns a fully populated Site whose pages are linked in prev/next order.
Exported types — Site, NavSection, NavItem, Page, TocItem — are the data model that the builder and server packages depend on.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LinkPrevNext ¶
func LinkPrevNext(pages []*Page)
LinkPrevNext sets Prev and Next on each page in the slice, which must already be in nav order (output of FlattenNav).
Types ¶
type Frontmatter ¶
Frontmatter holds the YAML front matter fields recognised by kwelea. All fields are optional; their zero values are sensible defaults.
type NavItem ¶
type NavItem struct {
}
NavItem is a single entry in the sidebar nav. Active is set by the renderer when this item matches the current page.
type NavSection ¶
type NavSection struct {
}
NavSection is a labelled group of pages in the sidebar. Label is empty ("") for root-level pages that have no section heading.
func Build ¶
func Build(pages []*Page, navEntries []config.NavEntry) ([]NavSection, error)
Build creates the navigation tree from the discovered pages. If navEntries is non-empty (manual [nav] sections from kwelea.toml) it uses those; otherwise it builds the nav automatically from the filesystem. An error is returned only when a manual nav ref is ambiguous.
type Page ¶
type Page struct {
Title string
TitleFromFrontmatter bool // true when Title came from frontmatter; false when derived from filename
Description string
Path string // canonical URL path, e.g. /getting-started/
FilePath string // source .md file, relative to docs_dir
HTML template.HTML // filled by parser (Phase 3)
TOC []TocItem // filled by parser (Phase 3)
Prev *Page
Next *Page
Draft bool
}
Page holds all data needed to render a single documentation page. HTML and TOC are zero until Phase 3 fills them in via the parser.
func FlattenNav ¶
func FlattenNav(sections []NavSection, pages []*Page) []*Page
FlattenNav returns all unique Pages from the nav sections in order. The result is used to assign Prev/Next links.
func WalkDocs ¶
WalkDocs discovers all non-draft .md files under docsDir and returns them as Page values with metadata populated. HTML and TOC are left empty until Phase 3 fills them in via the Markdown parser.
Files are returned in the order filepath.WalkDir visits them — lexical order within each directory. The nav builder re-sorts within sections to put index.md pages first.
type Site ¶
type Site struct {
Title string
Version string
BaseURL string
BasePath string // URL path prefix derived from BaseURL, e.g. "/kwelea" or ""
Repo string
RepoPlatform string // "github", "gitlab", or "" for unknown/not set
BuildCfg config.BuildConfig
ServeCfg config.ServeConfig
ThemeCfg config.ThemeConfig
Pages []*Page // flat ordered list for prev/next linking
}
Site is the root context passed to every template render. It is built once per build and then treated as read-only.
Source Files