Documentation
¶
Overview ¶
Package build orchestrates the full site build pipeline.
Index ¶
- Constants
- func BundleEmbeddedJS(embeddedFS fs.FS, devMode bool) ([]byte, string, error)
- func ContentHash(content string) string
- func KnownPluginNames() []string
- func PageOutputPath(relPermalink string) string
- func WriteEmbeddedAssets(embeddedFS fs.FS, outputDir string, tracker *OutputTracker, ...) error
- func WriteEmbeddedCSS(outputDir string, css string, filename string, tracker *OutputTracker) error
- type BuildError
- type BuildOptions
- type CacheEntry
- type CheckOptions
- type CheckResult
- type Minifier
- type OutputTracker
- type PageCache
- type RenderedPage
- type SiteBuilder
- type ValidateResult
- type Writer
Constants ¶
const DefaultPageCacheCapacity = 512
Variables ¶
This section is empty.
Functions ¶
func BundleEmbeddedJS ¶
BundleEmbeddedJS concatenates all JS files under assets/js/ in the embedded theme FS into a single bundle, wrapping each in an IIFE. In production mode the bundle is minified via esbuild. Returns the bundled content and a filename (fingerprinted in production, plain in dev).
func ContentHash ¶
ContentHash returns the sha256 hex digest of raw content.
func KnownPluginNames ¶
func KnownPluginNames() []string
KnownPluginNames returns the union of all valid plugin names from the Go-side registry, subpackage plugins, and client-side manifest.
func PageOutputPath ¶
PageOutputPath converts a RelPermalink to an output file path. "/" → "index.html" "/docs/intro/" → "docs/intro/index.html" "/404.html" → "404.html"
func WriteEmbeddedAssets ¶
func WriteEmbeddedAssets(embeddedFS fs.FS, outputDir string, tracker *OutputTracker, skipPrefixes []string) error
WriteEmbeddedAssets walks the `assets/` subtree inside the given embedded theme filesystem and writes every file to outputDir/assets/. Files under any of the skipPrefixes are skipped (used to exclude bundled JS). It is a no-op when the `assets/` directory is absent.
func WriteEmbeddedCSS ¶
func WriteEmbeddedCSS(outputDir string, css string, filename string, tracker *OutputTracker) error
WriteEmbeddedCSS writes the embedded CSS bundle to outputDir/assets/css/<filename>.
Types ¶
type BuildError ¶
type BuildError struct {
Type string // "template", "frontmatter", "markdown", "build"
File string // relative file path
Line int // 1-based line number
Col int // 1-based column number
Message string // error message
Frame string // ±3 lines of source context
}
BuildError holds structured information about a build failure.
func ParseBuildError ¶
func ParseBuildError(err error, projectDir string) *BuildError
ParseBuildError extracts structured error info from a build error. Returns nil if the error cannot be parsed into a structured form.
type BuildOptions ¶
type BuildOptions struct {
ProjectDir string
Config *config.SiteConfig
ThemeConfig *engine.ThemeConfig
EmbeddedFS fs.FS
DevMode bool // Skip heavy optimizations during serve (image processing, minification, etc.)
PluginAssetsDir string // If set, recompute plugin client bundles from disk (theme-dev mode)
}
BuildOptions provides the inputs for creating a SiteBuilder.
type CacheEntry ¶
type CacheEntry struct {
ContentHash string `json:"content_hash"`
HTML string `json:"html"`
Headings []engine.Heading `json:"headings"`
HasCodeBlocks bool `json:"has_code_blocks,omitempty"`
HasImages bool `json:"has_images,omitempty"`
Links []engine.CollectedLink `json:"links,omitempty"`
}
CacheEntry holds the cached result of rendering a page's markdown.
type CheckOptions ¶
type CheckOptions struct {
External bool // enable external URL probing
Strict bool // override all policies to "error"
ReportFormat string // override report format ("pretty" | "json" | "github-actions")
}
CheckOptions controls the behavior of the Check method.
type CheckResult ¶
type CheckResult struct {
PageCount int
LinkCount int
Lanes int
HasErrors bool
Findings []links.Finding
Warnings []engine.ValidationWarning
Output string // formatted report output
Summary string
Duration time.Duration
}
CheckResult holds the outcome of a link-check-only run.
type Minifier ¶
type Minifier struct {
// contains filtered or unexported fields
}
Minifier wraps tdewolff/minify for HTML minification.
func (*Minifier) MinifyHTML ¶
MinifyHTML minifies HTML content. Returns the original on error (non-fatal).
type OutputTracker ¶
type OutputTracker struct {
// contains filtered or unexported fields
}
OutputTracker records every file written during a build so orphaned files from previous builds can be pruned without a full RemoveAll.
func NewOutputTracker ¶
func NewOutputTracker(sizeHint int) *OutputTracker
NewOutputTracker creates an OutputTracker pre-sized for the expected number of output files.
func (*OutputTracker) Prune ¶
func (t *OutputTracker) Prune(outputDir string) error
Prune walks outputDir and removes any file not in the written set, then removes empty directories bottom-up.
func (*OutputTracker) Track ¶
func (t *OutputTracker) Track(path string)
Track records a path as written. Thread-safe.
func (*OutputTracker) TrackBatch ¶
func (t *OutputTracker) TrackBatch(paths []string)
TrackBatch records multiple paths as written in a single lock acquisition.
type PageCache ¶
type PageCache struct {
Dir string
// contains filtered or unexported fields
}
PageCache is a two-layer (in-memory LRU + filesystem) content-addressed cache for rendered markdown. Safe for concurrent use.
func NewPageCache ¶
NewPageCache creates a PageCache with the default capacity.
func (*PageCache) Get ¶
func (c *PageCache) Get(hash string) *CacheEntry
Get retrieves a cached entry by content hash. Checks in-memory LRU first, then falls through to filesystem.
The returned *CacheEntry (including its Headings/Links slices) is shared with the in-memory LRU and, on a hit, with every other caller of the same hash. Callers MUST treat it as read-only: mutating it (e.g. appending to Headings) would corrupt the cache and other pages. Copy before mutating if needed.
func (*PageCache) Put ¶
func (c *PageCache) Put(hash string, entry *CacheEntry)
Put stores a cache entry in both in-memory LRU and filesystem.
type RenderedPage ¶
type RenderedPage struct {
Page *engine.Page
HTML []byte
OutPath string // relative to output dir (e.g., "docs/intro/index.html")
}
RenderedPage holds a rendered page and its output path.
type SiteBuilder ¶
type SiteBuilder struct {
// contains filtered or unexported fields
}
SiteBuilder orchestrates the full six-phase build pipeline.
func NewSiteBuilder ¶
func NewSiteBuilder(opts BuildOptions) *SiteBuilder
NewSiteBuilder creates a SiteBuilder with all dependencies initialized.
func (*SiteBuilder) Build ¶
func (b *SiteBuilder) Build() (*engine.BuildResult, error)
Build executes the full six-phase pipeline and writes output to disk.
func (*SiteBuilder) Check ¶
func (b *SiteBuilder) Check(opts CheckOptions) (*CheckResult, error)
Check runs the build pipeline through link validation and returns the report without rendering templates or writing HTML to disk.
func (*SiteBuilder) ContentRebuild ¶
func (b *SiteBuilder) ContentRebuild(changedPaths []string) (*engine.BuildResult, error)
ContentRebuild performs an incremental rebuild for content-only changes. It re-parses only the changed files, patches them into the existing collections, and renders/writes only the dirty pages. Falls back to full Build() on edge cases.
func (*SiteBuilder) Validate ¶
func (b *SiteBuilder) Validate() (*ValidateResult, error)
Validate runs phases 1-4 (Initialize, Discover, Parse, Assemble) without rendering or writing.
type ValidateResult ¶
type ValidateResult struct {
PageCount int
Collections int
Warnings []engine.ValidationWarning
Pages []*engine.Page
Duration time.Duration
}
ValidateResult holds the outcome of a validation run (no rendering or writing).
Source Files