plugin

Documentation

Overview

Package plugin provides canonical type definitions for the huan plugin system.

Package plugin provides canonical type definitions for the huan plugin system.

Both huan internal code and .so plugins import these types, solving Go's cross-module type assertion problem for interface-based capability discovery.

Plugin is the minimal base interface every plugin satisfies. Capability interfaces (e.g. pkg/plugin.Hook, pkg/plugin.ThemePlugin) embed Plugin and add domain-specific methods. The Registry holds plugins keyed by Name(); Find[T] returns the subset implementing a given capability.

Package plugin provides canonical type definitions for the huan plugin system.

Index

• func Find[T any](r *Registry) []T
• type FieldSchema
• type Hook
• type MetadataProvider
• type Plugin
• type PluginMeta
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) All() []Plugin
  • func (r *Registry) Get(name string) (Plugin, bool)
  • func (r *Registry) Names() []string
  • func (r *Registry) Register(p Plugin) error
  • func (r *Registry) SortedNames() []string
  • func (r *Registry) Unregister(name string) bool
• type Schema
• type SchemaProvider
• type ShortcodeContext
• type ShortcodeHandler
• type ShortcodeProvider
• type TemplateEntry
• type ThemeHooks
• type ThemeInfo
• type ThemePlugin

Functions

func Find

func Find[T any](r *Registry) []T

Find returns all registered plugins implementing capability T, in registration order. T is typically a capability interface such as pkg/plugin.Hook or pkg/plugin.ThemePlugin.

Example:

hooks := plugin.Find[pkgplugin.Hook](registry)
for _, h := range hooks { ... }

Types

type FieldSchema

type FieldSchema struct {
	Key         string // 字段名，对应 yaml key
	Type        string // "string" | "int" | "bool" | "string_slice" | "map"
	Required    bool   // true = 必填，启动时校验
	Default     any    // 默认值（Required=false 时生效）
	Description string // 人类可读的说明
	Sensitive   bool   // true = 在 CLI info 中 mask 为 ***
	EnvVarHint  string // 建议的环境变量名，仅用于文档提示
}

FieldSchema describes a single config field.

type Hook

type Hook interface {
	Plugin

	// OnContentLoaded is called after all content files are loaded and parsed.
	// The plugin receives the full page list and may return a modified list.
	// Returning nil (or the same slice) is a no-op.
	OnContentLoaded(ctx context.Context, pages []interface{}) ([]interface{}, error)

	// OnPageRendered is called after each page is rendered to HTML.
	OnPageRendered(ctx context.Context, page interface{}) error

	// OnOutputWritten is called after all output files are written but before
	// the build result is finalized. Receives the output directory path for
	// post-processing.
	OnOutputWritten(ctx context.Context, outputDir string) error
}

Hook is the capability interface for plugins that participate in the build pipeline. Each method maps to a BuildSite stage.

Every method is optional — a plugin that only needs to run after writing output implements OnOutputWritten and returns nil for the others.

Hook methods use interface{} for page references to avoid importing the content package, which is not importable from pkg/plugin/ or from .so plugin modules.

type MetadataProvider

type MetadataProvider interface {
	PluginMetadata() PluginMeta
}

MetadataProvider is an optional interface plugins can implement to provide their metadata. Used by the LifecycleManager.List() and Admin/CLI UI.

type Plugin

type Plugin interface {
	// Name is the plugin's unique identifier. It matches the yaml key under
	// plugins: (e.g. Name()=="seo_injector" pairs with yaml plugins.seo_injector.*).
	Name() string
}

Plugin is the base interface every plugin satisfies. Capability interfaces embed Plugin and add methods.

Plugin intentionally has only Name(): config injection happens via the plugin's constructor (e.g. seoinjector.New(cfg)), not via an Init method.

type PluginMeta

type PluginMeta struct {
	Version    string   `json:"version"`
	Author     string   `json:"author"`
	RepoURL    string   `json:"repoURL"`
	License    string   `json:"license"`
	Tags       []string `json:"tags"`
	IsOfficial bool     `json:"isOfficial"`
}

PluginMeta carries human-readable metadata for a plugin.

type Registry

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

Registry holds plugins keyed by Name(). The order slice preserves registration order for deterministic iteration in Find[T] and All.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty Registry.

func (*Registry) All

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

All returns all registered plugins in registration order. The returned slice is a copy; callers may mutate it without affecting the registry.

func (*Registry) Get

func (r *Registry) Get(name string) (Plugin, bool)

Get returns the plugin with the given name and a found flag.

func (*Registry) Names

func (r *Registry) Names() []string

Names returns all registered plugin names in registration order.

func (*Registry) Register

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

Register adds a plugin to the registry. Returns an error if a plugin with the same Name() is already registered — duplicate registration is treated as a programming error rather than silently overwritten.

func (*Registry) SortedNames

func (r *Registry) SortedNames() []string

SortedNames returns registered plugin names in lexicographic order. Useful for CLI listing where deterministic alphabetical output is preferred over registration order.

func (*Registry) Unregister

func (r *Registry) Unregister(name string) bool

Unregister removes a plugin by name. Returns false if the name wasn't registered. After Unregister, the plugin is no longer returned by Get, All, Names, or Find[T].

type Schema

type Schema struct {
	Fields []FieldSchema
}

Schema describes the full config shape a plugin expects.

type SchemaProvider

type SchemaProvider interface {
	ConfigSchema() Schema
}

SchemaProvider is an optional interface plugins can implement to declare their config schema. Used by the registry for config validation.

type ShortcodeContext

type ShortcodeContext struct {
	Params map[string]string
	Inner  string
}

ShortcodeContext carries the parameters and context for a shortcode invocation.

type ShortcodeHandler

type ShortcodeHandler func(ctx ShortcodeContext) (string, error)

ShortcodeHandler is a function that renders a shortcode.

type ShortcodeProvider

type ShortcodeProvider interface {
	Shortcodes() map[string]ShortcodeHandler
}

ShortcodeProvider is an optional interface that themes can implement to register custom shortcodes.

type TemplateEntry

type TemplateEntry struct {
	Path    string // Logical path, e.g. "index.html"
	Content string // Template content
}

TemplateEntry describes a single template file.

type ThemeHooks

type ThemeHooks interface {
	BeforeRender(ctx context.Context) error
	AfterRender(ctx context.Context) error
}

ThemeHooks is an optional interface that themes can implement to inject lifecycle hooks into the render pipeline.

type ThemeInfo

type ThemeInfo struct {
	Name        string   `json:"name"`
	Version     string   `json:"version"`
	Author      string   `json:"author"`
	Description string   `json:"description"`
	Screenshot  string   `json:"screenshot,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	MinHuanVer  string   `json:"minHuanVer,omitempty"`
}

ThemeInfo carries theme metadata.

type ThemePlugin

type ThemePlugin interface {
	Plugin

	// Info returns the theme's metadata as a key-value map.
	Info() map[string]any

	// Templates returns the list of templates the theme provides.
	// Each entry has "path" and "content" keys.
	Templates() []map[string]string

	// FuncMap returns the theme's custom template functions.
	FuncMap() template.FuncMap

	// Assets returns the theme's static asset filesystem.
	Assets() fs.FS
}

ThemePlugin is the core capability interface for theme plugins. Themes provide templates, template functions, and static assets for site rendering.

Note: Methods use interface{} and built-in types (not concrete structs) so that .so plugins loaded via Go's plugin.Open can satisfy this interface across module boundaries. Concrete struct types would be different named types in each module and fail type assertions.