plugin

package
v0.3.0-beta.9 Latest Latest
Warning

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

Go to latest
Published: Sep 7, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var DefaultRegistry = NewRegistry()

DefaultRegistry is the global plugin registry.

Functions

func CloseGoPlugins

func CloseGoPlugins()

CloseGoPlugins terminates every running Go plugin subprocess.

func Register

func Register(p Plugin) error

Register adds a plugin to the default registry.

func RunAfterBuild

func RunAfterBuild(ctx *BuildResultHookCtx) error

RunAfterBuild runs all AfterBuild hooks sorted by order.

func RunAfterMarkdownParse

func RunAfterMarkdownParse(ctx *MarkdownHookCtx) error

RunAfterMarkdownParse runs all AfterMarkdownParse hooks sorted by order.

func RunAfterPage

func RunAfterPage(ctx *PageHookCtx) error

RunAfterPage runs all AfterPage hooks sorted by order.

func RunAfterParse

func RunAfterParse(ctx *ParseHookCtx) error

RunAfterParse runs all AfterParse hooks sorted by order.

func RunAfterRender

func RunAfterRender(ctx *RenderHookCtx) error

RunAfterRender runs all AfterRender hooks sorted by order.

func RunBeforeBuild

func RunBeforeBuild(ctx *BuildHookCtx) error

RunBeforeBuild runs all BeforeBuild hooks sorted by order.

func RunCommunityPlugins

func RunCommunityPlugins(hookName string, plugins []config.PluginConfig, root, outDir string, hookCtx interface{}) error

RunCommunityPlugins runs all configured community plugins for the given hook. pluginConfig is the full plugins list from config; hookName identifies which hook is being executed; hookCtx is the JSON-serializable context for the hook. Community plugins are JavaScript modules (config plugins[].module points to a .js/.mjs/.cjs file) executed inside the embedded QuickJS runtime.

Types

type BuildHookCtx

type BuildHookCtx struct {
	Root           string           `json:"root"`
	OutDir         string           `json:"outDir"`
	Config         interface{}      `json:"config,omitempty"` // *config.Config
	Pages          []string         `json:"pages"`
	GeneratedPages *[]GeneratedPage `json:"generatedPages,omitempty"` // mutable — append generated pages here
	DevMode        bool             `json:"devMode"`
}

BuildHookCtx is passed to BeforeBuild and GenerateRoutes hooks.

type BuildResultHookCtx

type BuildResultHookCtx struct {
	Root   string       `json:"root"`
	OutDir string       `json:"outDir"`
	Config interface{}  `json:"config,omitempty"` // *config.Config
	Pages  []PageResult `json:"pages"`
	CSS    string       `json:"css"`
}

BuildResultHookCtx is passed to AfterBuild hook after all pages are built.

type DocsPlugin

type DocsPlugin struct{}

func (*DocsPlugin) Hooks

func (p *DocsPlugin) Hooks() PluginHooks

func (*DocsPlugin) Name

func (p *DocsPlugin) Name() string

func (*DocsPlugin) Order

func (p *DocsPlugin) Order() int

type DocsPluginOptions

type DocsPluginOptions struct {
	ContentDir string             `json:"contentDir"`
	Title      string             `json:"title"`
	Layout     string             `json:"layout"`
	Sidebar    []docs.SidebarItem `json:"sidebar"`
	Links      []SocialLink       `json:"links"`
	Search     *DocsSearchOptions `json:"search"`
}

type DocsSearchOptions

type DocsSearchOptions struct {
	// Enabled turns the search bar on/off. Default: true.
	Enabled bool `json:"enabled"`
	// Engine selects the index backend. "docfind" (default) embeds a WASM
	// search index built in-process from the docs; "json" uses the classic
	// search-index.json fallback. The client falls back to JSON automatically
	// if the WASM index is unavailable.
	Engine string `json:"engine"`
	// MaxResults caps the number of results shown. Default: 8.
	MaxResults int `json:"maxResults"`
}

DocsSearchOptions configures the docs site search bar.

type GeneratedPage

type GeneratedPage struct {
	Path  string `json:"path"`  // absolute filesystem path to the generated .tsx file
	Route string `json:"route"` // URL path e.g. "docs/getting-started"
}

GeneratedPage describes a TSX page generated by a plugin (e.g., docs plugin).

type HookFunc

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

HookFunc is a convenience type that implements Plugin using plain functions.

func (*HookFunc) Hooks

func (h *HookFunc) Hooks() PluginHooks

func (*HookFunc) Name

func (h *HookFunc) Name() string

func (*HookFunc) Order

func (h *HookFunc) Order() int

type MarkdownHookCtx

type MarkdownHookCtx struct {
	Page  string `json:"page"`
	HTML  string `json:"html"` // mutable — plugin can modify rendered HTML
	Title string `json:"title"`
	Route string `json:"route"`
}

MarkdownHookCtx is passed to AfterMarkdownParse hook after markdown rendering.

type PageHookCtx

type PageHookCtx struct {
	Page     string `json:"page"`
	OutName  string `json:"outName"`
	HTML     string `json:"html"`     // mutable — plugin can modify final HTML
	HeadHTML string `json:"headHTML"` // mutable — plugin can inject head content
	HasJS    bool   `json:"hasJS"`
}

PageHookCtx is passed to AfterPage hook after a page is fully built including layout wrapping. All pointer fields are mutable.

type PageResult

type PageResult struct {
	Page     string `json:"page"`
	OutName  string `json:"outName"`
	HTML     string `json:"html"`
	HeadHTML string `json:"headHTML"`
	HasJS    bool   `json:"hasJS"`
}

PageResult is a single page's output in the AfterBuild hook.

type ParseHookCtx

type ParseHookCtx struct {
	Page    string       `json:"page"`
	Program *ast.Program `json:"program,omitempty"`
}

ParseHookCtx is passed to AfterParse hook after a page's source is parsed.

type Plugin

type Plugin interface {
	// Name returns a unique identifier for this plugin.
	Name() string
	// Order returns execution priority. Lower values run first. Default is 50.
	Order() int
	// Hooks returns the lifecycle hooks this plugin implements.
	Hooks() PluginHooks
}

Plugin is the unified plugin interface. Every plugin — built-in or community — implements this single interface. Plugins declare which lifecycle hooks they use via Hooks(). Only non-nil hooks are called.

func NewHookFunc

func NewHookFunc(name string, order int, hooks PluginHooks) Plugin

NewHookFunc creates a Plugin from a name, order, and hooks.

type PluginHooks

type PluginHooks struct {
	// BeforeBuild runs before any page is built. Plugins can generate TSX files
	// and append them to ctx.GeneratedPages to create new pages.
	BeforeBuild func(ctx *BuildHookCtx) error

	// AfterParse runs after a page's source is parsed into an AST.
	// Useful for inspecting or modifying the AST before rendering.
	AfterParse func(ctx *ParseHookCtx) error

	// AfterMarkdownParse runs after a markdown page is rendered to HTML.
	// Plugins can modify the HTML before it enters the layout pipeline.
	AfterMarkdownParse func(ctx *MarkdownHookCtx) error

	// AfterRender runs after a page is rendered to HTML but BEFORE layout
	// wrapping. Plugins can modify HTML, inject head content, or add CSS.
	AfterRender func(ctx *RenderHookCtx) error

	// GenerateRoutes runs after BeforeBuild. Return virtual pages that should
	// be built alongside real source pages.
	GenerateRoutes func(ctx *BuildHookCtx) ([]Route, error)

	// AfterPage runs after a page is fully built including layout wrapping.
	// Receives the final HTML and OutName. Plugins can modify output.
	AfterPage func(ctx *PageHookCtx) error

	// AfterBuild runs once after ALL pages are built and aggregate work is done.
	// The full set of page results and merged CSS is available.
	AfterBuild func(ctx *BuildResultHookCtx) error
}

PluginHooks holds optional lifecycle hook functions. Only non-nil hooks are invoked. Plugins implement the hooks they need.

type Registry

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

Registry holds all registered plugins (single unified registry).

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty plugin registry.

func (*Registry) Add

func (r *Registry) Add(p Plugin) error

Add registers a plugin. Returns error on duplicate name.

func (*Registry) List

func (r *Registry) List() []Plugin

List returns all registered plugins.

func (*Registry) Sorted

func (r *Registry) Sorted() []Plugin

Sorted returns all plugins sorted by Order (ascending).

type RenderHookCtx

type RenderHookCtx struct {
	Page     string `json:"page"`
	HTML     string `json:"html"`     // mutable — plugin can modify rendered HTML
	HeadHTML string `json:"headHTML"` // mutable — plugin can inject head content
	HasJS    bool   `json:"hasJS"`
	RawCSS   string `json:"rawCSS"` // mutable — plugin can inject additional CSS
}

RenderHookCtx is passed to AfterRender hook after a page is fully rendered but before layout wrapping. All pointer fields are mutable.

type Route

type Route struct {
	Path    string            `json:"path"`
	Content string            `json:"content"`
	Title   string            `json:"title"`
	Layout  string            `json:"layout,omitempty"`
	Data    map[string]string `json:"data,omitempty"`
}

Route represents a virtual page generated by a plugin.

func RunGenerateRoutes

func RunGenerateRoutes(ctx *BuildHookCtx) ([]Route, error)

RunGenerateRoutes runs all GenerateRoutes hooks and returns combined routes.

type ServeRequestArgs

type ServeRequestArgs struct {
	URL     string            `json:"url"`
	Method  string            `json:"method"`
	Path    string            `json:"path"`
	Headers map[string]string `json:"headers"`
}

ServeRequestArgs is the wire context for the ServeRequest hook. It mirrors the middleware request shape so plugins transform the incoming request.

type ServeRequestResult

type ServeRequestResult struct {
	Action  string            `json:"action"`
	Status  int               `json:"status"`
	Headers map[string]string `json:"headers"`
	Body    string            `json:"body"`
	NewURL  string            `json:"newURL"`
	Error   string            `json:"error,omitempty"`
}

ServeRequestResult is the wire result for the ServeRequest hook, matching the middleware result shape: 'continue' to fall through, 'rewrite' to rewrite the path, or 'respond' to short-circuit with a custom response.

func RunServeRequest

func RunServeRequest(plugins []config.PluginConfig, root, url, method, path string, headers map[string]string) (*ServeRequestResult, error)

RunServeRequest runs the ServeRequest hook across every configured community plugin (in config order) and returns the first response, or nil to continue.

type ServeResponseArgs

type ServeResponseArgs struct {
	URL     string            `json:"url"`
	Method  string            `json:"method"`
	Path    string            `json:"path"`
	Status  int               `json:"status"`
	Headers map[string]string `json:"headers"`
	Body    string            `json:"body"`
}

ServeResponseArgs is the wire context for the ServeResponse hook. It wraps a buffered non-streaming response so plugins can inspect and rewrite it.

type ServeResponseResult

type ServeResponseResult struct {
	Status  int               `json:"status"`
	Headers map[string]string `json:"headers"`
	Body    string            `json:"body"`
	Error   string            `json:"error,omitempty"`
}

ServeResponseResult returns the (possibly rewritten) buffered response.

func RunServeResponse

func RunServeResponse(plugins []config.PluginConfig, root, url, method, path string, status int, headers map[string]string, body string) (ServeResponseResult, error)

RunServeResponse runs the ServeResponse hook across every configured community plugin and returns the final buffered response.

type SitemapPluginOptions

type SitemapPluginOptions struct {
	BaseURL    string `json:"baseUrl"`
	ChangeFreq string `json:"changeFreq,omitempty"` // always|hourly|daily|weekly|monthly|yearly|never
	Priority   string `json:"priority,omitempty"`   // 0.0 - 1.0 (default "0.5")
}

SitemapPluginOptions holds typed configuration for the sitemap plugin.

type SocialLink struct {
	Icon string `json:"icon"`
	URL  string `json:"url"`
}

Directories

Path Synopsis
Package searchassets embeds the docs search UI files (search.js + search.css) that the docs plugin writes into the output directory at build time.
Package searchassets embeds the docs search UI files (search.js + search.css) that the docs plugin writes into the output directory at build time.

Jump to

Keyboard shortcuts

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