Skip to main content

Plugin

ssg::plugin

Trait Plugin 

Source 
pub trait Plugin:
    Debug
    + Send
    + Sync {
    // Required method
    fn name(&self) -> &str;

    // Provided methods
    fn before_compile(&self, _ctx: &PluginContext) -> Result<()> { ... }
    fn after_compile(&self, _ctx: &PluginContext) -> Result<()> { ... }
    fn transform_html(
        &self,
        html: &str,
        _path: &Path,
        _ctx: &PluginContext,
    ) -> Result<String> { ... }
    fn has_transform(&self) -> bool { ... }
    fn on_serve(&self, _ctx: &PluginContext) -> Result<()> { ... }
}
Expand description

Trait for SSG plugins.

Implement this trait to create a plugin that hooks into the site generation lifecycle. All hooks have default no-op implementations, so you only need to override the ones you care about.

§Stability contract

This trait is part of the SSG public API. The stability commitment for the 1.0 line is:

  1. All current hook signatures are frozen. Once 1.0 ships, no parameter, return type, or trait bound on an existing method will change without a major version bump.
  2. New hooks land with a default Ok(()) implementation. Adding a new hook is therefore non-breaking — existing impl Plugin for … blocks continue to compile.
  3. PluginContext is #[non_exhaustive]. New fields (e.g. additional caches, link graphs, image metadata) can be added without breaking downstream construction sites — those are constructed inside SSG, not by plugin authors.
  4. Removing a hook requires a major bump. Hook removal is rare and always preceded by a deprecation cycle of at least one minor release with #[deprecated] and a migration note in the CHANGELOG.

See API stability audit for the full Tier-A inventory.

Required Methods§

Source

fn name(&self) -> &str

Returns the unique name of this plugin.

Provided Methods§

Source

fn before_compile(&self, _ctx: &PluginContext) -> Result<()>

Called before site compilation begins.

Use this hook to preprocess content files, inject metadata, or validate source directories.

Source

fn after_compile(&self, _ctx: &PluginContext) -> Result<()>

Called after site compilation completes.

Use this hook to post-process generated HTML, optimize assets, generate sitemaps, or perform any output transformation.

Source

fn transform_html( &self, html: &str, _path: &Path, _ctx: &PluginContext, ) -> Result<String>

Per-file HTML transform hook — called once per HTML file during the fused transform pass.

Receives the current HTML content and returns the (possibly modified) HTML. The default implementation returns the input unchanged.

Plugins that implement this hook avoid redundant file I/O — the pipeline reads each HTML file once, pipes it through all plugins’ transform_html hooks, then writes the result once.

Source

fn has_transform(&self) -> bool

Returns true if this plugin implements transform_html. Override to true to opt in to the fused transform pass.

Source

fn on_serve(&self, _ctx: &PluginContext) -> Result<()>

Called before the development server starts serving files.

Use this hook to inject dev-mode scripts, set up live-reload, or modify the serve directory.

Implementors§