plugin

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Aug 29, 2026 License: MIT Imports: 24 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.

View Source 
const RenderedFallbackMaxChars = 160

RenderedFallbackMaxChars is the description budget used by consumers that fall back to RenderedTextFallback, matching the 160-character convention of the transformer's auto-description.

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 ExtractSearchText added in v1.2.0 

func ExtractSearchText(s string) string

ExtractSearchText returns the searchable plain text of rendered page HTML. Unlike StripHTML it parses the markup, so it can drop subtrees that render as UI rather than prose (diagram DSLs, raw math source, code line-number gutters) and it decodes entities exactly once. Whitespace is collapsed and a space is inserted at element boundaries, matching StripHTML's shape. On a parse failure it falls back to StripHTML.

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 RenderedTextFallback added in v1.2.0 

func RenderedTextFallback(content template.HTML, maxChars int) string

RenderedTextFallback returns a plain-text excerpt of rendered page HTML, truncated to at most maxChars at a word boundary, for use as a last-resort description when both the frontmatter description and the auto-generated summary are empty (e.g. a body that is entirely directive blocks, which the raw-markdown summary extractor rightly skips). Entities are left encoded: callers apply a single terminal html.UnescapeString so the value is decoded exactly once.

func ShouldExcludePath added in v1.2.0 

func ShouldExcludePath(urlPath string, patterns []string) bool

ShouldExcludePath checks if a URL path matches any exclude pattern. Uses path.Match (slash-separated glob semantics on every platform); filepath.Match would make patterns behave differently on Windows. Exported for subpackage plugins (e.g. telescope) that share the same exclude-pattern semantics.

func StripHTML added in v1.2.0 

func StripHTML(s string) string

StripHTML removes HTML tags and collapses whitespace, inserting a space at tag boundaries so adjacent elements do not run together.

func TrimTitlePrefix added in v1.2.0 

func TrimTitlePrefix(text, title string) string

TrimTitlePrefix drops a leading title prefix from a rendered-text excerpt. The rendered body usually opens with the page's own H1, which reads as duplication anywhere the title is already displayed alongside the text.

func TruncateRuneSafe added in v1.2.0 

func TruncateRuneSafe(s string, max int) string

TruncateRuneSafe cuts s to at most max bytes without splitting a UTF-8 rune.

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()

	// ProjectDir is the absolute path of the project root, for plugins that
	// resolve user-supplied files (e.g. a logo under public/).
	ProjectDir string

	// 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.

Source Files

View all Source files

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 catalog assembles the machine-readable plugin catalog behind `sarde plugins --format json`: every plugin name the engine accepts in plugins.enabled, with metadata and configurable fields.
 Package catalog assembles the machine-readable plugin catalog behind `sarde plugins --format json`: every plugin name the engine accepts in plugins.enabled, with metadata and configurable fields.
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").
Package serverplugins is the declarative registry of Sarde's built-in server-side plugins: manifest.yaml carries their metadata and defaults/<name>.yaml their configurable fields, in the same blueprint shape used by clientplugins and external plugin blueprints.
 Package serverplugins is the declarative registry of Sarde's built-in server-side plugins: manifest.yaml carries their metadata and defaults/<name>.yaml their configurable fields, in the same blueprint shape used by clientplugins and external plugin blueprints.
Package telescope provides a built-in plugin that adds a command-palette style quick-navigation modal, opened with Ctrl+/ (Cmd+/ on Mac).
 Package telescope provides a built-in plugin that adds a command-palette style quick-navigation modal, opened with Ctrl+/ (Cmd+/ on Mac).

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.