Skip to main content

​
Plugins Overview

Scully’s plugin system is the foundation of its extensibility, allowing you to customize and control every aspect of the static site generation process. Whether you need to fetch dynamic routes, transform HTML content, or execute custom logic at specific points in the build lifecycle, plugins provide the mechanism to do so.

​
What are Scully Plugins?

A Scully plugin is a function that returns a promise (or an async function) that integrates with Scully’s rendering pipeline. Plugins allow you to:
  • Discover and generate routes dynamically from data sources
  • Transform rendered HTML content
  • Handle different file types (Markdown, AsciiDoc, etc.)
  • Execute custom logic before or after the build process
  • Integrate with external services and APIs

​
Plugin Philosophy

Scully’s plugin architecture is designed with several key principles: Composability: Plugins can be combined and chained together to create complex transformations and workflows. Lifecycle Integration: Plugins hook into specific points in Scully’s build process, giving you precise control over when your code executes. Graceful Error Handling: When a plugin fails, Scully handles it gracefully. You can control whether Scully continues rendering or stops on error using the --pluginsError=false command-line option. Performance Monitoring: Scully automatically gathers timing data from every plugin execution, helping you identify performance bottlenecks.

​
Plugin Categories

Scully organizes plugins into three main categories:

​
Built-in Plugins

Scully comes with a comprehensive set of built-in plugins that handle common tasks:
  • contentFolder: Discovers and renders content from markdown and AsciiDoc files
  • json: Fetches route data from JSON endpoints
  • md: Processes Markdown files with syntax highlighting
  • seoHrefOptimise: Optimizes href attributes for SEO
  • flashPrevention: Prevents flash of unstyled content
These plugins are automatically registered and ready to use in your Scully configuration.

​
Community Plugins

The Scully community has created numerous plugins for specialized tasks:
  • @gammastream/scully-plugin-sitemap: Generates XML sitemaps
  • scully-plugin-toc: Creates table of contents
  • @scullyio/scully-plugin-minify-html: Minifies HTML output
  • scully-plugin-lazy-images: Implements lazy loading for images
  • @notiz/scully-plugin-rss: Generates RSS feeds
Community plugins are installed via npm and imported into your Scully configuration.

​
Custom Plugins

You can create your own plugins to meet specific requirements. Custom plugins follow the same patterns as built-in plugins and can be easily registered and reused across projects.

​
Plugin Types

Scully provides eleven distinct plugin types, each serving a specific purpose in the build pipeline:
Plugin TypePurposeExecution Point
beforeAllExecute tasks before Scully starts processingBefore any processing begins
routerDiscover and generate routes from data sourcesDuring route discovery
routeProcessTransform the collected route arrayAfter routes are discovered
routeDiscoveryDoneExecute logic after all routes are collectedAfter route discovery completes
fileHandlerProcess different file types (MD, ADOC, etc.)During content rendering
postProcessByDomTransform HTML using DOM manipulationAfter initial render
postProcessByHtmlTransform HTML as stringAfter DOM processing
allDoneExecute tasks after all rendering completesAfter all routes are rendered
enterpriseCustom enterprise-level integrationsVariable
scullySystemSystem-level plugins for core functionalityVariable
renderTransform rendered HTML (deprecated)Use postProcessByHtml instead

​
Quick Start Example

Here’s a simple example of using plugins in your scully.config.ts: 
import { ScullyConfig, setPluginConfig } from '@scullyio/scully';

// Import a community plugin
import { getSitemapPlugin } from '@gammastream/scully-plugin-sitemap';

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'my-app',
  outDir: './dist/static',
  routes: {
    // Using the built-in contentFolder plugin
    '/blog/:slug': {
      type: 'contentFolder',
      slug: {
        folder: './blog'
      }
    }
  }
};

// Configure a community plugin
const SitemapPlugin = getSitemapPlugin();
setPluginConfig(SitemapPlugin, {
  urlPrefix: 'https://mysite.com',
  sitemapFilename: 'sitemap.xml'
});

​
Error Handling

Scully’s plugin system includes robust error handling:
  • By default, plugin errors stop the build process
  • Use --pluginsError=false to continue rendering even when plugins fail
  • All plugin errors are logged with detailed information
  • Errors include the plugin name, type, and route being processed
# Continue on plugin errors
npx scully --pluginsError=false

​
Performance Tracking

Scully automatically tracks the performance of every plugin execution:
  • Each plugin invocation is measured using performance.mark()
  • Timing data helps identify slow plugins
  • Performance metrics are available in Scully’s output

​
Next Steps

To dive deeper into Scully’s plugin system:

Build docs developers (and LLMs) love

Get started for freeTalk to us