Documentation
¶
Overview ¶
Package directive implements site- and theme-authored generic directives: data-driven ::: blocks defined by a directives/<name>.yaml schema, an <name>.html html/template, and an optional <name>.css sidecar. The package is goldmark-agnostic; the parsing/rendering side lives in internal/content/markdown/extensions/genericdirective.
Index ¶
- Constants
- func MergeCatalog(base *engine.DirectiveCatalog, regs ...*Registry) *engine.DirectiveCatalog
- func ValidName(name string) bool
- type Def
- type Registry
- func (r *Registry) CSS() string
- func (r *Registry) CatalogEntries() []engine.CatalogDirective
- func (r *Registry) Empty() bool
- func (r *Registry) Hash() string
- func (r *Registry) LoadDir(dir, source string) []engine.ValidationWarning
- func (r *Registry) Lookup(name string) *Def
- func (r *Registry) Names() []string
- func (r *Registry) ValidateAgainstBuiltins(cat *engine.DirectiveCatalog) []engine.ValidationWarning
- type TemplateData
Constants ¶
const ( KindContainer = "container" KindLeaf = "leaf" )
KindContainer directives have a markdown body rendered recursively; KindLeaf directives capture their body as raw text.
Variables ¶
This section is empty.
Functions ¶
func MergeCatalog ¶
func MergeCatalog(base *engine.DirectiveCatalog, regs ...*Registry) *engine.DirectiveCatalog
MergeCatalog returns a new catalog combining the embedded built-in catalog with every registry's generic directives. Built-in entries are stamped Source "builtin"; generic directives land in one appended "custom" category. base is not mutated. Later registries win name conflicts among themselves; built-in name conflicts cannot occur because ValidateAgainstBuiltins removes them at load time.
Types ¶
type Def ¶
type Def struct {
Name string
Kind string // KindContainer | KindLeaf
Label string
Description string
Category string
Source string // "site" | "theme" | "plugin:<slug>"
Bracket *engine.CatalogDirectiveBracket
Fields []engine.CatalogDirectiveField
Template *htmltemplate.Template
CSS []byte
// contains filtered or unexported fields
}
Def is one loaded generic directive definition.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds all loaded generic directive definitions. Load order gives overlay precedence: a directory loaded later overwrites same-named directives from earlier directories (plugins first, then theme, then site). The registry is immutable after loading and safe for concurrent read access.
func NewRegistry ¶
func NewRegistry(funcMap htmltemplate.FuncMap) *Registry
NewRegistry creates an empty Registry. funcMap is applied to every directive template (the shortcode FuncMap: icon, i18n, URL helpers).
func (*Registry) CSS ¶
CSS returns all directive CSS sidecars concatenated in name order, each prefixed with a header comment. Empty string when no directive ships CSS.
func (*Registry) CatalogEntries ¶
func (r *Registry) CatalogEntries() []engine.CatalogDirective
CatalogEntries converts every definition into its catalog form, sorted by name. Kind maps to the catalog's "block"; every field placement is "attr".
func (*Registry) Hash ¶
Hash returns a sha256 hex digest over every definition's name, YAML, template, and CSS bytes, sorted by name. Folded into the markdown renderer's fingerprint so the page cache busts on any directive change. Empty string for an empty registry.
func (*Registry) LoadDir ¶
func (r *Registry) LoadDir(dir, source string) []engine.ValidationWarning
LoadDir loads every <name>.yaml + <name>.html pair in dir, stamping source ("site" or "theme") on each definition. A missing dir is not an error. Invalid definitions are skipped with a warning; valid ones still load.
func (*Registry) ValidateAgainstBuiltins ¶
func (r *Registry) ValidateAgainstBuiltins(cat *engine.DirectiveCatalog) []engine.ValidationWarning
ValidateAgainstBuiltins removes any directive whose name collides with a built-in catalog entry, returning one warning per removal. Built-ins always win: their bespoke parsers register ahead of the generic extension, so a colliding definition would silently never run.
type TemplateData ¶
type TemplateData struct {
Name string // directive name
Label string // bracket label or ""
Attrs map[string]string // attrutil.Parse of the opening fence; missing keys read ""
Body htmltemplate.HTML // container: rendered children HTML; leaf: escaped raw text
}
TemplateData is the pipeline value every generic directive template executes against.
Source Files