plugin

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: 21 Imported by: 0

Documentation

Overview

Package plugin implements the 4-hook plugin lifecycle system and built-in plugins.

Index

Constants

View Source
const LangAwareAnnouncementFunc = "__sarde_announcementBannerForLang"

LangAwareAnnouncementFunc is an internal template func factory key used by the announcements plugin so concurrent multilingual renders do not share mutable language state.

Variables

This section is empty.

Functions

func BuiltinNames

func BuiltinNames() []string

builtinRegistry maps plugin names to their constructor functions. Each constructor receives the plugin's config from sarde.yaml plugins.config.<name>.

Plugins that live in subpackages (to keep their embedded vendor assets isolated) cannot appear here because it would create an import cycle. They are registered from internal/build/builder.go via Manager.Register. BuiltinNames returns the names of all plugins registered in the built-in registry. It does not include subpackage plugins (katex, mermaid, etc.) or client-side plugins from the manifest.

func LintPages

func LintPages(pages []*engine.Page, lint config.ContentLintSettings) []engine.ValidationWarning

LintPages runs content lint rules on a set of pages and returns warnings. This is exported so that the validate command can call it directly without going through the plugin BuildDone hook.

func MatchesInjectRule added in v1.0.0

func MatchesInjectRule(rule string, page *engine.Page, rd *engine.RouteData) bool

MatchesInjectRule evaluates a declarative inject-condition rule against a page and its route data. Shared by the clientplugins manifest loader and the external plugin loader. Unknown rules never match.

func WriteFSTree added in v1.0.0

func WriteFSTree(ctx *BuildDoneContext, fsys fs.FS, root, destPrefix string) error

WriteFSTree copies every file under root in fsys into the build output, rewriting each path from root/... to destPrefix + ... . Used by plugins that ship embedded vendor asset trees (KaTeX, Mermaid).

func WriteFSTreeFiltered added in v1.0.0

func WriteFSTreeFiltered(ctx *BuildDoneContext, fsys fs.FS, root, destPrefix string, include func(rel string) bool) error

WriteFSTreeFiltered is WriteFSTree with an optional include filter applied to each root-relative file path. A nil filter copies everything.

Types

type BeforeRenderContext

type BeforeRenderContext struct {
	Page         *engine.Page
	RouteData    *engine.RouteData
	Site         *engine.SiteContext
	Resolver     *engine.URLResolver
	PluginConfig map[string]any
	// contains filtered or unexported fields
}

BeforeRenderContext is available per-page before template rendering.

func (*BeforeRenderContext) AbsURL

func (c *BeforeRenderContext) AbsURL(relPath, lang, version string) string

AbsURL returns a fully-qualified URL (origin + resolved path).

func (*BeforeRenderContext) BaseURL added in v1.0.0

func (c *BeforeRenderContext) BaseURL() string

BaseURL returns the site base URL without its trailing slash, or "".

func (*BeforeRenderContext) Get

func (c *BeforeRenderContext) Get(key string) any

Get retrieves a value from the shared cross-hook store.

func (*BeforeRenderContext) ResolveURL

func (c *BeforeRenderContext) ResolveURL(relPath, lang, version string) string

ResolveURL returns a root-relative URL with basePath, lang, and version applied.

func (*BeforeRenderContext) Set

func (c *BeforeRenderContext) Set(key string, value any)

Set stores a value in the shared cross-hook store.

type BuildDoneContext

type BuildDoneContext struct {
	Config         *config.SiteConfig
	PluginConfig   map[string]any
	OutputDir      string
	Pages          []*engine.Page
	Collections    map[string]*engine.Collection
	Site           *engine.SiteContext
	Resolver       *engine.URLResolver
	PageIndex      *content.PageIndex                // page index for link validation
	ValidationData map[string]engine.ValidationEntry // permalink -> collected links per page
	DevMode        bool
	Incremental    bool // true after an incremental rebuild rather than a full Build()

	// ChangedPages holds the pages whose parsed content actually changed
	// during an incremental rebuild. Nil on full builds, non-empty whenever
	// Incremental is true (the incremental path only reaches BuildDone when
	// at least one page changed). Plugins that want per-page work
	// proportional to a save's actual diff should branch on Incremental and
	// use ChangedPages instead of Pages.
	ChangedPages []*engine.Page

	// RemovedPermalinks lists permalinks removed by this rebuild. Always nil
	// today: new and deleted content files force a full rebuild, so the
	// incremental path never has removals to report. Reserved for a future
	// incremental path that handles deletions without falling back.
	RemovedPermalinks []string

	TrackFn func(string)
	// contains filtered or unexported fields
}

BuildDoneContext is available after all files are written. Thread-safe for parallel use.

func (*BuildDoneContext) AbsURL

func (c *BuildDoneContext) AbsURL(relPath, lang, version string) string

AbsURL returns a fully-qualified URL (origin + resolved path).

func (*BuildDoneContext) AddWarning

func (c *BuildDoneContext) AddWarning(w engine.ValidationWarning)

AddWarning appends a validation warning. Thread-safe.

func (*BuildDoneContext) BaseURL added in v1.0.0

func (c *BuildDoneContext) BaseURL() string

BaseURL returns the site base URL without its trailing slash, or "".

func (*BuildDoneContext) Log

func (c *BuildDoneContext) Log(message string)

Log emits a build log message prefixed with the plugin's name.

func (*BuildDoneContext) ResolveURL

func (c *BuildDoneContext) ResolveURL(relPath, lang, version string) string

ResolveURL returns a root-relative URL with basePath, lang, and version applied.

func (*BuildDoneContext) SetLogger

func (c *BuildDoneContext) SetLogger(l *engine.BuildLogger)

SetLogger sets the build logger. Must be called before RunBuildDone.

func (*BuildDoneContext) SetWarnings

func (c *BuildDoneContext) SetWarnings(w *[]engine.ValidationWarning)

SetWarnings sets the warnings slice pointer. Must be called before RunBuildDone.

func (*BuildDoneContext) WriteFile

func (c *BuildDoneContext) WriteFile(relPath string, data []byte) error

WriteFile writes a file to the output directory. Thread-safe.

type ConfigSetupContext

type ConfigSetupContext struct {
	Config        *config.SiteConfig
	PluginConfig  map[string]any
	TemplateFuncs map[string]any // collected via AddTemplateFunc
	// contains filtered or unexported fields
}

ConfigSetupContext is available after config is loaded, before content discovery.

func (*ConfigSetupContext) AddTemplateFunc

func (c *ConfigSetupContext) AddTemplateFunc(name string, fn any)

AddTemplateFunc registers a template function to be available in templates.

func (*ConfigSetupContext) Get

func (c *ConfigSetupContext) Get(key string) any

Get retrieves a value from the shared cross-hook store.

func (*ConfigSetupContext) Set

func (c *ConfigSetupContext) Set(key string, value any)

Set stores a value in the shared cross-hook store.

type ContentLoadedContext

type ContentLoadedContext struct {
	Config       *config.SiteConfig
	PluginConfig map[string]any
	Collections  map[string]*engine.Collection
	Pages        *[]*engine.Page // pointer — plugins can append via InjectPage
	// contains filtered or unexported fields
}

ContentLoadedContext is available after content parsing, before assembly.

func (*ContentLoadedContext) Get

func (c *ContentLoadedContext) Get(key string) any

Get retrieves a value from the shared cross-hook store.

func (*ContentLoadedContext) InjectPage

func (c *ContentLoadedContext) InjectPage(page *engine.Page)

InjectPage appends a virtual page to the page list.

func (*ContentLoadedContext) Set

func (c *ContentLoadedContext) Set(key string, value any)

Set stores a value in the shared cross-hook store.

type Manager

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

Manager orchestrates plugin registration and lifecycle hook execution.

func NewManager

func NewManager() *Manager

NewManager creates an empty plugin manager.

func (*Manager) Register

func (m *Manager) Register(p *Plugin)

Register adds a plugin to the manager.

func (*Manager) RegisterBuiltins

func (m *Manager) RegisterBuiltins(enabled []string, configs map[string]map[string]any)

RegisterBuiltins registers all enabled built-in plugins.

func (*Manager) RunBeforeRender

func (m *Manager) RunBeforeRender(cfg *config.SiteConfig, page *engine.Page, rd *engine.RouteData, site *engine.SiteContext, resolver *engine.URLResolver) error

RunBeforeRender executes BeforeRender hooks serially for a single page.

func (*Manager) RunBuildDone

func (m *Manager) RunBuildDone(ctx *BuildDoneContext) error

RunBuildDone executes BuildDone hooks in parallel for all plugins.

func (*Manager) RunConfigSetup

func (m *Manager) RunConfigSetup(cfg *config.SiteConfig) error

RunConfigSetup executes ConfigSetup hooks serially for all plugins.

func (*Manager) RunContentLoaded

func (m *Manager) RunContentLoaded(cfg *config.SiteConfig, collections map[string]*engine.Collection, pages *[]*engine.Page) error

RunContentLoaded executes ContentLoaded hooks serially for all plugins.

func (*Manager) TemplateFuncs

func (m *Manager) TemplateFuncs() map[string]any

TemplateFuncs returns template functions collected from ConfigSetup hooks.

type Plugin

type Plugin struct {
	Name  string
	Hooks PluginHooks
}

Plugin is a named bundle of lifecycle hooks.

type PluginHooks

type PluginHooks struct {
	ConfigSetup   func(ctx *ConfigSetupContext) error
	ContentLoaded func(ctx *ContentLoadedContext) error
	BeforeRender  func(ctx *BeforeRenderContext) error
	BuildDone     func(ctx *BuildDoneContext) error
}

PluginHooks holds optional hook functions. Nil hooks are not called.

type SharedStore

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

SharedStore is a simple key-value store for cross-hook data passing. It is safe for concurrent BeforeRender hooks.

func NewStore

func NewStore() *SharedStore

NewStore creates an empty shared store.

func (*SharedStore) Get

func (s *SharedStore) Get(key string) any

Get retrieves a value by key. Returns nil if not found.

func (*SharedStore) Set

func (s *SharedStore) Set(key string, value any)

Set stores a value by key.

Directories

Path Synopsis
Package announcements provides a built-in plugin that renders dismissible announcement banners at the bottom of every page.
Package announcements provides a built-in plugin that renders dismissible announcement banners at the bottom of every page.
Package clientplugins provides a declarative manifest-driven loader for client-side plugins.
Package clientplugins provides a declarative manifest-driven loader for client-side plugins.
Package external loads declarative disk-based plugins from {project}/plugins/{slug}/.
Package external loads declarative disk-based plugins from {project}/plugins/{slug}/.
Package katex provides a built-in plugin that ships KaTeX runtime assets and wires them into any page whose rendered HTML contains math markup.
Package katex provides a built-in plugin that ships KaTeX runtime assets and wires them into any page whose rendered HTML contains math markup.
Package mermaid provides a built-in plugin that ships Mermaid runtime assets and wires them into pages whose rendered HTML contains a mermaid diagram (class="sarde-mermaid").
Package mermaid provides a built-in plugin that ships Mermaid runtime assets and wires them into pages whose rendered HTML contains a mermaid diagram (class="sarde-mermaid").

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL