@terrymooreii/sia 2.2.0 → 2.3.0

package/docs/plugins.md

@@ -0,0 +1,320 @@
+# Plugin System
+
+Sia includes a powerful plugin system that allows you to extend functionality at key points in the build lifecycle. Plugins can be created locally in your project or published as npm packages.
+
+## Overview
+
+Plugins are JavaScript modules that export a plugin object with hooks that execute at specific points during the build process. They can:
+
+- Transform content before or after parsing
+- Generate additional files (search indexes, sitemaps, etc.)
+- Add custom Marked extensions for markdown processing
+- Register custom Nunjucks template filters and functions
+- Modify site data before rendering
+- Perform post-build tasks
+
+## Configuration
+
+Plugins are configured in your `_config.yml` or `_config.json` file:
+
+```yaml
+plugins:
+  enabled: true          # Master switch (default: true)
+  strictMode: false      # Fail build on plugin errors (default: false)
+  order:                 # Explicit plugin execution order (optional)
+    - sia-search-plugin
+    - sia-sitemap-plugin
+  plugins: []            # Explicit list of plugins to load (optional, empty = all)
+  config:                # Plugin-specific configuration
+    sia-search-plugin:
+      outputPath: search-index.json
+      includeContent: false
+```
+
+### Configuration Options
+
+- **enabled**: Set to `false` to disable all plugins
+- **strictMode**: If `true`, the build will fail if any plugin has an error. If `false` (default), errors are logged but the build continues
+- **order**: Array of plugin names specifying execution order. Plugins not in this list will execute after, in dependency order
+- **plugins**: Array of plugin names to explicitly load. If empty or omitted, all discovered plugins are loaded
+- **config**: Object containing plugin-specific configuration, keyed by plugin name
+
+## Available Hooks
+
+Hooks are functions that plugins can register to execute at specific points in the build process.
+
+### Build Lifecycle Hooks
+
+#### `beforeBuild(config, api)`
+Executes before the build starts, after configuration is loaded.
+
+**Parameters:**
+- `config`: Site configuration object
+- `api`: Plugin API object (see Plugin API section)
+
+**Use cases:** Initialize plugin state, validate configuration, set up external services
+
+#### `afterConfigLoad(config, api)`
+Executes immediately after configuration is loaded, before any build steps.
+
+**Parameters:**
+- `config`: Site configuration object
+- `api`: Plugin API object
+
+**Use cases:** Modify configuration, validate plugin requirements
+
+#### `afterContentLoad(siteData, config, api)`
+Executes after all content collections are loaded and parsed.
+
+**Parameters:**
+- `siteData`: Complete site data object with collections, tags, etc.
+- `config`: Site configuration object
+- `api`: Plugin API object
+
+**Use cases:** Analyze content, generate metadata, modify collections
+
+#### `afterTagCollections(tags, context, api)`
+Executes after tag collections are built.
+
+**Parameters:**
+- `tags`: Tag collections object
+- `context`: Object with `config` and `collections`
+- `api`: Plugin API object
+
+**Use cases:** Modify tag data, generate tag statistics
+
+#### `beforeSiteData(siteData, config, api)`
+Executes before final siteData is created, allowing modification.
+
+**Parameters:**
+- `siteData`: Site data object (can be modified)
+- `config`: Site configuration object
+- `api`: Plugin API object
+
+**Use cases:** Add custom data to siteData, modify collections
+
+#### `beforeRender(siteData, config, api)`
+Executes before templates are rendered.
+
+**Parameters:**
+- `siteData`: Site data object
+- `config`: Site configuration object
+- `api`: Plugin API object
+
+**Use cases:** Prepare data for rendering, modify siteData for templates
+
+#### `afterRender(siteData, config, api)`
+Executes after all templates are rendered but before assets are copied.
+
+**Parameters:**
+- `siteData`: Site data object
+- `config`: Site configuration object
+- `api`: Plugin API object
+
+**Use cases:** Post-process rendered HTML, generate additional files
+
+#### `afterBuild(siteData, config, api)`
+Executes after the build completes, including asset copying.
+
+**Parameters:**
+- `siteData`: Site data object
+- `config`: Site configuration object
+- `api`: Plugin API object
+
+**Use cases:** Generate search indexes, create sitemaps, upload files, send notifications
+
+### Content Processing Hooks
+
+#### `beforeContentParse(rawContent, filePath)`
+Executes before a markdown file is parsed. Can modify the raw content.
+
+**Parameters:**
+- `rawContent`: Raw file content (string)
+- `filePath`: Path to the file
+
+**Returns:** Modified content string (or original if unchanged)
+
+**Use cases:** Pre-process markdown, inject content, transform syntax
+
+#### `afterContentParse(item, filePath)`
+Executes after a content item is parsed. Can modify the item.
+
+**Parameters:**
+- `item`: Parsed content item object
+- `filePath`: Path to the file
+
+**Returns:** Modified item object (or original if unchanged)
+
+**Use cases:** Add custom metadata, transform content, modify front matter
+
+#### `beforeMarkdown(markdown, context)`
+Executes before markdown is converted to HTML. Can modify the markdown.
+
+**Parameters:**
+- `markdown`: Markdown content (string)
+- `context`: Object with `filePath` and `frontMatter`
+
+**Returns:** Modified markdown string (or original if unchanged)
+
+**Use cases:** Transform markdown syntax, inject content
+
+#### `afterMarkdown(html, context)`
+Executes after markdown is converted to HTML. Can modify the HTML.
+
+**Parameters:**
+- `html`: Generated HTML (string)
+- `context`: Object with `filePath` and `frontMatter`
+
+**Returns:** Modified HTML string (or original if unchanged)
+
+**Use cases:** Post-process HTML, inject scripts, modify structure
+
+### Template Hooks
+
+#### `addTemplateFilter(env, config)`
+Allows plugins to register custom Nunjucks filters.
+
+**Parameters:**
+- `env`: Nunjucks environment object
+- `config`: Site configuration object
+
+**Use cases:** Add custom template filters for data transformation
+
+**Example:**
+```javascript
+hooks: {
+  addTemplateFilter: (env, config) => {
+    env.addFilter('uppercase', (str) => str.toUpperCase());
+  }
+}
+```
+
+#### `addTemplateFunction(env, config)`
+Allows plugins to register custom Nunjucks functions.
+
+**Parameters:**
+- `env`: Nunjucks environment object
+- `config`: Site configuration object
+
+**Use cases:** Add custom template functions for complex operations
+
+**Example:**
+```javascript
+hooks: {
+  addTemplateFunction: (env, config) => {
+    env.addGlobal('getApiData', async (url) => {
+      // Fetch and return data
+    });
+  }
+}
+```
+
+### Marked Extension Hook
+
+Plugins can add custom Marked extensions using the `addMarkedExtension` function from the plugin API or by using the `beforeBuild` hook to call it.
+
+**Example:**
+```javascript
+import { addMarkedExtension } from '@terrymooreii/sia';
+
+hooks: {
+  beforeBuild: (config, api) => {
+    addMarkedExtension({
+      renderer: {
+        // Custom renderer
+      }
+    });
+  }
+}
+```
+
+## Plugin API
+
+The `api` object passed to hooks provides utilities for plugins:
+
+### `api.config`
+Full site configuration object (read-only recommended)
+
+### `api.writeFile(path, content)`
+Write a file to the output directory.
+
+**Parameters:**
+- `path`: File path relative to output directory
+- `content`: File content (string)
+
+### `api.readFile(path)`
+Read a file from the filesystem.
+
+**Parameters:**
+- `path`: Absolute file path
+
+**Returns:** File content (string)
+
+### `api.joinPath(...paths)`
+Join path segments (wrapper around Node.js `path.join`).
+
+**Parameters:**
+- `...paths`: Path segments
+
+**Returns:** Joined path (string)
+
+### `api.log(message, level)`
+Log a message.
+
+**Parameters:**
+- `message`: Log message (string)
+- `level`: Log level - `'info'`, `'warn'`, or `'error'` (default: `'info'`)
+
+## Plugin Structure
+
+A plugin must export an object with the following structure:
+
+```javascript
+export default {
+  name: 'plugin-name',        // Required: Unique plugin identifier
+  version: '1.0.0',            // Required: Plugin version
+  dependencies: [],             // Optional: Array of plugin names this depends on
+  configSchema: {},            // Optional: Configuration schema
+  hooks: {                     // Optional: Hook functions
+    afterBuild: async (siteData, config, api) => {
+      // Plugin logic
+    }
+  }
+};
+```
+
+### Required Fields
+
+- **name**: Unique identifier for the plugin (string)
+- **version**: Plugin version (string)
+
+### Optional Fields
+
+- **dependencies**: Array of plugin names that must load before this plugin
+- **configSchema**: Object describing plugin configuration options (for documentation)
+- **hooks**: Object mapping hook names to hook functions
+
+## Plugin Discovery
+
+Sia discovers plugins from two sources:
+
+1. **Local plugins**: Files in the `_plugins/` directory (`.js` or `.mjs` files)
+2. **NPM packages**: Packages in `node_modules` matching the pattern `sia-plugin-*`
+
+Plugins are loaded in dependency order, or in the order specified in `config.plugins.order`.
+
+## Error Handling
+
+By default, plugin errors are logged but don't stop the build. Set `plugins.strictMode: true` in your config to fail the build on plugin errors.
+
+Errors include:
+- Plugin loading failures
+- Hook execution errors
+- Validation errors
+
+Error messages include the plugin name and detailed error information.
+
+## Examples
+
+See [Creating Plugins](./creating-plugins.md) for detailed examples of creating local and npm package plugins.
+

package/lib/build.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, rmSync } from 'fs';
+import { existsSync, mkdirSync, rmSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { loadConfig } from './config.js';
@@ -6,6 +6,8 @@ import { buildSiteData, paginate, getPaginationUrls } from './collections.js';
 import { createTemplateEngine, renderTemplate } from './templates.js';
 import { copyImages, copyDefaultStyles, copyStaticAssets, copyCustomAssets, copyContentAssets, writeFile, ensureDir } from './assets.js';
 import { resolveTheme } from './theme-resolver.js';
+import { loadPlugins } from './plugins.js';
+import { initializeHooks, registerPluginHooks, executeHook } from './hooks.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -195,6 +197,28 @@ function renderRSSFeed(env, siteData) {
   console.log('📡 Generated RSS feed');
 }
 
+/**
+ * Create plugin API object for hooks
+ */
+function createPluginAPI(config) {
+  return {
+    config,
+    writeFile: (path, content) => {
+      writeFile(path, content);
+    },
+    readFile: (path) => {
+      return readFileSync(path, 'utf-8');
+    },
+    joinPath: (...paths) => {
+      return join(...paths);
+    },
+    log: (message, level = 'info') => {
+      const prefix = level === 'error' ? '❌' : level === 'warn' ? '⚠️' : 'ℹ️';
+      console.log(`${prefix} ${message}`);
+    }
+  };
+}
+
 /**
  * Main build function
  */
@@ -206,6 +230,32 @@ export async function build(options = {}) {
   // Load configuration
   const config = loadConfig(options.rootDir || process.cwd());
   
+  // Initialize plugin system
+  initializeHooks();
+  
+  // Load plugins
+  let plugins = [];
+  try {
+    plugins = await loadPlugins(config);
+    
+    // Register plugin hooks
+    if (plugins.length > 0) {
+      registerPluginHooks(plugins);
+    }
+  } catch (err) {
+    if (config.plugins?.strictMode) {
+      throw err;
+    }
+    console.warn(`⚠️  Plugin loading error: ${err.message}`);
+  }
+  
+  // Execute afterConfigLoad hook
+  const pluginAPI = createPluginAPI(config);
+  await executeHook('afterConfigLoad', config, pluginAPI);
+  
+  // Execute beforeBuild hook
+  await executeHook('beforeBuild', config, pluginAPI);
+  
   // Only show drafts in dev mode if explicitly enabled in config
   // For production builds, always disable showDrafts
   if (!options.devMode) {
@@ -225,14 +275,23 @@ export async function build(options = {}) {
   const resolvedTheme = resolveTheme(themeName, config.rootDir);
   
   // Build site data (collections, tags, etc.)
-  const siteData = buildSiteData(config);
+  const siteData = await buildSiteData(config);
+  
+  // Execute afterContentLoad hook
+  await executeHook('afterContentLoad', siteData, config, pluginAPI);
+  
+  // Execute beforeSiteData hook (allows modification of siteData)
+  await executeHook('beforeSiteData', siteData, config, pluginAPI);
   
   // Copy custom assets and add to siteData
   const customAssets = copyCustomAssets(config);
   siteData.customAssets = customAssets;
   
   // Create template engine with resolved theme
-  const env = createTemplateEngine(config, resolvedTheme);
+  const env = await createTemplateEngine(config, resolvedTheme);
+  
+  // Execute beforeRender hook
+  await executeHook('beforeRender', siteData, config, pluginAPI);
   
   // Render all content items
   let itemCount = 0;
@@ -261,17 +320,23 @@ export async function build(options = {}) {
   // Generate RSS feed
   renderRSSFeed(env, siteData);
   
+  // Execute afterRender hook
+  await executeHook('afterRender', siteData, config, pluginAPI);
+  
   // Copy assets
   copyImages(config);
   copyDefaultStyles(config, resolvedTheme);
   // Custom assets already copied above and added to siteData
   copyStaticAssets(config);
   
+  // Execute afterBuild hook
+  await executeHook('afterBuild', siteData, config, pluginAPI);
+  
   const duration = ((Date.now() - startTime) / 1000).toFixed(2);
   console.log(`\n✅ Build complete in ${duration}s`);
   console.log(`📁 Output: ${config.outputDir}\n`);
   
-  return { config, siteData };
+  return { config, siteData, plugins };
 }
 
 /**

package/lib/collections.js

@@ -1,4 +1,5 @@
 import { loadAllCollections } from './content.js';
+import { executeHook } from './hooks.js';
 
 /**
  * Build tag collections from all content
@@ -102,9 +103,9 @@ export function getPaginationUrls(baseUrl, pagination, basePath = '') {
 /**
  * Build the complete site data structure
  */
-export function buildSiteData(config) {
+export async function buildSiteData(config) {
   // Load all content collections
-  const collections = loadAllCollections(config);
+  const collections = await loadAllCollections(config);
   
   // Build tag collections
   const tagCollections = buildTagCollections(collections);
@@ -112,6 +113,9 @@ export function buildSiteData(config) {
   
   console.log(`🏷️  Found ${allTags.length} unique tags`);
   
+  // Execute afterTagCollections hook
+  await executeHook('afterTagCollections', tagCollections, { config, collections });
+  
   // Create paginated collections for listings
   const paginatedCollections = {};
   
@@ -129,7 +133,7 @@ export function buildSiteData(config) {
     }));
   }
   
-  return {
+  const siteData = {
     config,
     site: config.site,
     collections,
@@ -138,6 +142,8 @@ export function buildSiteData(config) {
     allTags,
     paginatedTags
   };
+  
+  return siteData;
 }
 
 /**

package/lib/config.js

@@ -48,6 +48,13 @@ const defaultConfig = {
   assets: {
     css: [],  // Array of custom CSS file paths (relative to root)
     js: []    // Array of custom JavaScript file paths (relative to root)
+  },
+  plugins: {
+    enabled: true,  // Master switch for plugins
+    strictMode: false,  // Fail build on plugin errors (default: continue)
+    order: [],  // Explicit plugin execution order (optional)
+    plugins: [],  // Explicit list of plugins to load (optional, empty = all)
+    config: {}  // Plugin-specific configuration
   }
 };
 

package/lib/content.js

@@ -10,6 +10,7 @@ import { markedSmartypants } from 'marked-smartypants';
 import markedAlert from 'marked-alert';
 import markedLinkifyIt from 'marked-linkify-it';
 import hljs from 'highlight.js';
+import { executeHook, executeHookWithResult, getHookRegistry } from './hooks.js';
 
 /**
  * Default emoji map for shortcode support
@@ -84,7 +85,7 @@ const emojis = {
 /**
  * Configure marked with syntax highlighting, emoji support, and enhanced markdown features
  */
-const marked = new Marked(
+let marked = new Marked(
   markedHighlight({
     langPrefix: 'hljs language-',
     highlight(code, lang) {
@@ -120,6 +121,13 @@ marked.setOptions({
   breaks: false
 });
 
+/**
+ * Add a Marked extension (for plugins)
+ */
+export function addMarkedExtension(extension) {
+  marked.use(extension);
+}
+
 /**
  * Extract YouTube video ID from various URL formats
  * Supports:
@@ -397,12 +405,22 @@ export function getDateFromFilename(filename) {
 /**
  * Parse a markdown file with front matter
  */
-export function parseContent(filePath) {
-  const content = readFileSync(filePath, 'utf-8');
+export async function parseContent(filePath) {
+  let content = readFileSync(filePath, 'utf-8');
+  
+  // Execute beforeParse hook
+  content = await executeHookWithResult('beforeContentParse', content, filePath);
+  
   const { data: frontMatter, content: markdown } = matter(content);
   
+  // Execute beforeMarkdown hook
+  let processedMarkdown = await executeHookWithResult('beforeMarkdown', markdown, { filePath, frontMatter });
+  
   // Parse markdown to HTML
-  let html = marked.parse(markdown);
+  let html = marked.parse(processedMarkdown);
+  
+  // Execute afterMarkdown hook
+  html = await executeHookWithResult('afterMarkdown', html, { filePath, frontMatter });
   
   // Convert any remaining YouTube/Giphy links to embeds (handles autolinked URLs)
   html = embedYouTubeVideos(html);
@@ -447,7 +465,7 @@ export function parseContent(filePath) {
     tags = tags.split(',').map(t => t.trim());
   }
   
-  return {
+  const item = {
     ...frontMatter,
     slug,
     date,
@@ -459,6 +477,11 @@ export function parseContent(filePath) {
     filePath,
     draft: frontMatter.draft || false
   };
+  
+  // Execute afterContentParse hook (allows modification of item)
+  const modifiedItem = await executeHookWithResult('afterContentParse', item, filePath);
+  
+  return modifiedItem;
 }
 
 /**
@@ -490,7 +513,7 @@ export function getMarkdownFiles(dir) {
 /**
  * Load all content from a collection directory
  */
-export function loadCollection(config, collectionName) {
+export async function loadCollection(config, collectionName) {
   const collectionConfig = config.collections[collectionName];
   
   if (!collectionConfig) {
@@ -501,10 +524,10 @@ export function loadCollection(config, collectionName) {
   const collectionDir = join(config.inputDir, collectionConfig.path);
   const files = getMarkdownFiles(collectionDir);
   
-  const items = files
-    .map(filePath => {
+  const items = await Promise.all(
+    files.map(async (filePath) => {
       try {
-        const item = parseContent(filePath);
+        const item = await parseContent(filePath);
         
         // Add collection-specific metadata
         item.collection = collectionName;
@@ -529,21 +552,23 @@ export function loadCollection(config, collectionName) {
         return null;
       }
     })
-    .filter(item => {
-      if (item === null) return false;
-      // Include drafts if showDrafts is enabled in server config
-      if (item.draft && config.server?.showDrafts) {
-        return true;
-      }
-      // Otherwise, exclude drafts
-      return !item.draft;
-    });
+  );
+  
+  const filteredItems = items.filter(item => {
+    if (item === null) return false;
+    // Include drafts if showDrafts is enabled in server config
+    if (item.draft && config.server?.showDrafts) {
+      return true;
+    }
+    // Otherwise, exclude drafts
+    return !item.draft;
+  });
   
   // Sort items
   const sortBy = collectionConfig.sortBy || 'date';
   const sortOrder = collectionConfig.sortOrder || 'desc';
   
-  items.sort((a, b) => {
+  filteredItems.sort((a, b) => {
     const aVal = a[sortBy];
     const bVal = b[sortBy];
     
@@ -560,17 +585,17 @@ export function loadCollection(config, collectionName) {
     return 0;
   });
   
-  return items;
+  return filteredItems;
 }
 
 /**
  * Load all collections defined in config
  */
-export function loadAllCollections(config) {
+export async function loadAllCollections(config) {
   const collections = {};
   
   for (const name of Object.keys(config.collections)) {
-    collections[name] = loadCollection(config, name);
+    collections[name] = await loadCollection(config, name);
     console.log(`📚 Loaded ${collections[name].length} items from "${name}" collection`);
   }
   
@@ -584,6 +609,7 @@ export default {
   getDateFromFilename,
   getMarkdownFiles,
   loadCollection,
-  loadAllCollections
+  loadAllCollections,
+  addMarkedExtension
 };