@terrymooreii/sia 2.1.6 → 2.1.8

package/bin/cli.js

@@ -14,6 +14,7 @@ import { devCommand } from '../lib/server.js';
 import { buildCommand } from '../lib/build.js';
 import { newCommand } from '../lib/new.js';
 import { initCommand } from '../lib/init.js';
+import { themeCommand } from '../lib/theme.js';
 
 program
   .name('sia')
@@ -47,5 +48,11 @@ program
   .option('-d, --draft', 'Save as draft (posts only)')
   .action(newCommand);
 
+program
+  .command('theme <name>')
+  .description('Create a new Sia theme package')
+  .option('-q, --quick', 'Skip prompts and use defaults')
+  .action(themeCommand);
+
 program.parse();
 

package/docs/README.md

@@ -54,8 +54,10 @@ npm run build
 - **Tags & Categories** - Organize content with tags and auto-generated tag pages
 - **Pagination** - Built-in pagination for listing pages
 - **Image Support** - Automatic image copying and organization
+- **Static Assets** - Support for favicons, fonts, and other static files
 - **Live Reload** - Development server with hot reloading
 - **Multiple Themes** - Built-in themes (main, minimal, developer, magazine) with light/dark mode
+- **Custom Theme Packages** - Create and share themes as npm packages (`sia-theme-*`)
 - **RSS Feed** - Automatic RSS feed generation
 - **SEO Ready** - Open Graph and Twitter Card meta tags included
 
@@ -69,6 +71,10 @@ my-site/
 │   ├── pages/           # Static pages
 │   ├── notes/           # Short notes/tweets
 │   └── images/          # Images
+├── assets/              # Static assets (optional)
+├── static/              # Static assets (optional)
+├── public/              # Static assets (optional)
+├── favicon.ico          # Site favicon (optional)
 ├── _layouts/            # Custom layouts (optional)
 ├── _includes/           # Custom includes (optional)
 ├── styles/              # Custom CSS (optional)
@@ -87,7 +93,8 @@ site:
   author: "Your Name"
 
 theme:
-  name: main  # Options: main, minimal, developer, magazine
+  name: main  # Built-in: main, minimal, developer, magazine
+              # Or use external: my-theme (loads sia-theme-my-theme)
 
 input: src
 output: dist
@@ -116,6 +123,58 @@ server:
   showDrafts: false
 ```
 
+## Static Assets
+
+Sia automatically copies static assets during the build process. You can place static files in any of these locations:
+
+- **`assets/`** - Place files in `assets/` at the project root
+- **`static/`** - Place files in `static/` at the project root
+- **`public/`** - Place files in `public/` at the project root
+- **Root directory** - Place `favicon.ico` directly in the project root
+
+All files from these directories will be copied to the `dist/` folder during build, preserving their directory structure.
+
+### Supported File Types
+
+Static assets include:
+- **Favicons** - `.ico` files (favicon.ico can be in root or asset directories)
+- **Fonts** - `.woff`, `.woff2`, `.ttf`, `.eot`
+- **Documents** - `.pdf`, `.txt`, `.json`, `.xml`
+- **Scripts** - `.js` files
+- **Stylesheets** - `.css` files (though custom CSS is better placed in `styles/`)
+- **Images** - All image formats (though images are better placed in `src/images/`)
+
+### Example Structure
+
+```
+my-site/
+├── assets/
+│   ├── favicon.ico
+│   ├── robots.txt
+│   ├── manifest.json
+│   └── fonts/
+│       └── custom-font.woff2
+├── static/
+│   └── documents/
+│       └── resume.pdf
+└── favicon.ico  # Also supported in root
+```
+
+During build, these will be copied to:
+```
+dist/
+├── assets/
+│   ├── favicon.ico
+│   ├── robots.txt
+│   ├── manifest.json
+│   └── fonts/
+│       └── custom-font.woff2
+├── static/
+│   └── documents/
+│       └── resume.pdf
+└── favicon.ico
+```
+
 ## CLI Commands
 
 | Command | Description |
@@ -126,6 +185,7 @@ server:
 | `sia new post "Title"` | Create a new blog post |
 | `sia new page "Title"` | Create a new page |
 | `sia new note "Content"` | Create a new note |
+| `sia theme <name>` | Create a new theme package |
 
 ## License
 

package/docs/creating-themes.md

@@ -1,6 +1,6 @@
 # Creating Themes
 
-This guide explains how to create custom themes for Sia and how to customize existing themes.
+This guide explains how to create custom themes for Sia, distribute them as npm packages, and customize existing themes.
 
 ## Table of Contents
 
@@ -13,6 +13,9 @@ This guide explains how to create custom themes for Sia and how to customize exi
 - [Styles](#styles)
 - [Shared Includes](#shared-includes)
 - [Dark Mode Support](#dark-mode-support)
+- [External Theme Packages](#external-theme-packages)
+- [Creating a Theme Package](#creating-a-theme-package)
+- [Publishing Your Theme](#publishing-your-theme)
 - [Customizing Existing Themes](#customizing-existing-themes)
 - [Built-in Themes](#built-in-themes)
 - [Best Practices](#best-practices)
@@ -649,6 +652,218 @@ toggle.addEventListener('click', () => {
 
 ---
 
+## External Theme Packages
+
+Sia supports distributing themes as npm packages, making it easy to share themes with the community.
+
+### How Theme Resolution Works
+
+When Sia loads a theme, it follows this resolution order:
+
+1. **Built-in themes** - First checks the `themes/` folder in the Sia package
+2. **npm packages** - If not found, looks for `sia-theme-{name}` in your `package.json` dependencies
+3. **Fallback** - Falls back to the "main" theme if nothing is found
+
+### Using an External Theme
+
+To use an external theme in your Sia site:
+
+```bash
+# Install the theme package
+npm install sia-theme-awesome
+```
+
+Then configure it in your `_config.yml`:
+
+```yaml
+theme:
+  name: awesome  # Sia will look for sia-theme-awesome
+```
+
+That's it! Sia automatically detects and uses the theme from `node_modules`.
+
+### Theme Package Requirements
+
+External theme packages must:
+
+1. **Follow naming convention** - Package name must be `sia-theme-{name}`
+2. **Export theme directory** - Include an `index.js` that exports the theme path
+3. **Include required files** - Have `layouts/` and `pages/` directories (minimum)
+4. **Follow theme structure** - Match the same structure as built-in themes
+
+---
+
+## Creating a Theme Package
+
+### Using the Theme Generator
+
+The easiest way to create a new theme is with the built-in generator:
+
+```bash
+sia theme my-awesome-theme
+```
+
+This creates a complete theme package with all necessary files:
+
+```
+sia-theme-my-awesome-theme/
+├── package.json          # npm package configuration
+├── index.js              # Exports theme directory path
+├── README.md             # Theme documentation
+├── layouts/
+│   ├── base.njk          # Base HTML template
+│   ├── post.njk          # Blog post layout
+│   ├── page.njk          # Static page layout
+│   └── note.njk          # Note layout
+├── includes/
+│   ├── header.njk        # Site header/navigation
+│   ├── footer.njk        # Site footer
+│   ├── hero.njk          # Homepage hero section
+│   ├── pagination.njk    # Pagination component
+│   └── tag-list.njk      # Tag cloud component
+├── pages/
+│   ├── index.njk         # Homepage
+│   ├── blog.njk          # Blog listing
+│   ├── notes.njk         # Notes listing
+│   ├── tags.njk          # All tags page
+│   ├── tag.njk           # Single tag page
+│   └── feed.njk          # RSS feed
+└── styles/
+    └── main.css          # Theme styles
+```
+
+### Generator Options
+
+```bash
+# Interactive mode (prompts for details)
+sia theme my-theme
+
+# Quick mode (skip prompts, use defaults)
+sia theme my-theme --quick
+sia theme my-theme -q
+```
+
+### package.json Structure
+
+The generated `package.json` includes:
+
+```json
+{
+  "name": "sia-theme-my-theme",
+  "version": "1.0.0",
+  "description": "My Theme theme for Sia static site generator",
+  "main": "index.js",
+  "type": "module",
+  "keywords": [
+    "sia",
+    "sia-theme",
+    "static-site",
+    "theme"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "peerDependencies": {
+    "@terrymooreii/sia": ">=2.0.0"
+  }
+}
+```
+
+### index.js Structure
+
+The `index.js` exports the theme directory for Sia to locate:
+
+```javascript
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Export the theme directory path for Sia to use
+export const themeDir = __dirname;
+export default themeDir;
+```
+
+### Manual Theme Creation
+
+If you prefer to create a theme manually:
+
+1. Create a new directory: `mkdir sia-theme-my-theme`
+2. Initialize npm: `npm init`
+3. Set the package name to `sia-theme-{name}`
+4. Create the required directory structure
+5. Add an `index.js` that exports the directory path
+6. Add all required template files
+
+---
+
+## Publishing Your Theme
+
+### Preparing for Publication
+
+1. **Test locally** - Link your theme and test with a Sia site:
+
+   ```bash
+   # In your theme directory
+   npm link
+   
+   # In a Sia site directory
+   npm link sia-theme-my-theme
+   ```
+
+2. **Update package.json** - Add repository, bugs, and homepage URLs:
+
+   ```json
+   {
+     "repository": {
+       "type": "git",
+       "url": "https://github.com/username/sia-theme-my-theme.git"
+     },
+     "bugs": {
+       "url": "https://github.com/username/sia-theme-my-theme/issues"
+     },
+     "homepage": "https://github.com/username/sia-theme-my-theme#readme"
+   }
+   ```
+
+3. **Write documentation** - Update the README with:
+   - Screenshots of the theme
+   - Installation instructions
+   - Configuration options
+   - Customization tips
+
+### Publishing to npm
+
+```bash
+# Login to npm (if not already)
+npm login
+
+# Publish the package
+npm publish
+
+# Or publish with public access if scoped
+npm publish --access public
+```
+
+### Versioning
+
+Follow semantic versioning:
+
+- **Patch** (1.0.1) - Bug fixes, minor style tweaks
+- **Minor** (1.1.0) - New features, backward-compatible changes
+- **Major** (2.0.0) - Breaking changes to templates or configuration
+
+### Theme Discovery
+
+To help users find your theme:
+
+1. Use `sia-theme` in your npm keywords
+2. Add a clear description
+3. Include screenshots in your README
+4. Consider creating a demo site
+
+---
+
 ## Customizing Existing Themes
 
 You don't need to create a full theme to customize your site.

package/lib/assets.js

@@ -10,6 +10,7 @@ import {
   rmdirSync
 } from 'fs';
 import { join, dirname, relative, extname } from 'path';
+import { resolveTheme, getBuiltInThemesDir } from './theme-resolver.js';
 
 // Supported asset extensions
 const IMAGE_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.gif', '.svg', '.webp', '.ico', '.avif'];
@@ -126,8 +127,11 @@ function hasCssFiles(dir) {
 
 /**
  * Copy default styles to output
+ * 
+ * @param {object} config - Site configuration
+ * @param {object} [resolvedTheme] - Pre-resolved theme info from resolveTheme()
  */
-export function copyDefaultStyles(config, themesDir) {
+export function copyDefaultStyles(config, resolvedTheme = null) {
   const outputStylesDir = join(config.outputDir, 'styles');
   
   // Check if user has custom styles (must actually have CSS files)
@@ -140,20 +144,23 @@ export function copyDefaultStyles(config, themesDir) {
     return copied;
   }
   
-  // Copy styles from the selected theme
+  // Resolve theme if not already resolved
   const themeName = config.theme?.name || 'main';
-  const themeStylesDir = join(themesDir, themeName, 'styles');
+  const theme = resolvedTheme || resolveTheme(themeName, config.rootDir);
+  const themeStylesDir = join(theme.themeDir, 'styles');
   
   if (existsSync(themeStylesDir)) {
     const copied = copyAssets(themeStylesDir, outputStylesDir);
-    console.log(`🎨 Using "${themeName}" theme`);
+    if (!theme.isExternal) {
+      console.log(`🎨 Using "${theme.themeName}" theme`);
+    }
     return copied;
   }
   
-  // Fallback to main theme if selected theme not found
-  const fallbackStylesDir = join(themesDir, 'main', 'styles');
+  // Fallback to main theme if theme styles not found
+  const fallbackStylesDir = join(getBuiltInThemesDir(), 'main', 'styles');
   if (existsSync(fallbackStylesDir)) {
-    console.log(`⚠️  Theme "${themeName}" not found, using "main" theme`);
+    console.log(`⚠️  Theme "${themeName}" styles not found, using "main" theme styles`);
     const copied = copyAssets(fallbackStylesDir, outputStylesDir);
     return copied;
   }

package/lib/build.js

@@ -5,10 +5,10 @@ import { loadConfig } from './config.js';
 import { buildSiteData, paginate, getPaginationUrls } from './collections.js';
 import { createTemplateEngine, renderTemplate } from './templates.js';
 import { copyImages, copyDefaultStyles, copyStaticAssets, writeFile, ensureDir } from './assets.js';
+import { resolveTheme } from './theme-resolver.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const themesDir = join(__dirname, '..', 'themes');
 
 /**
  * Clean the output directory
@@ -215,11 +215,15 @@ export async function build(options = {}) {
     cleanOutput(config);
   }
   
+  // Resolve theme once for both templates and assets
+  const themeName = config.theme?.name || 'main';
+  const resolvedTheme = resolveTheme(themeName, config.rootDir);
+  
   // Build site data (collections, tags, etc.)
   const siteData = buildSiteData(config);
   
-  // Create template engine
-  const env = createTemplateEngine(config);
+  // Create template engine with resolved theme
+  const env = createTemplateEngine(config, resolvedTheme);
   
   // Render all content items
   let itemCount = 0;
@@ -244,7 +248,7 @@ export async function build(options = {}) {
   
   // Copy assets
   copyImages(config);
-  copyDefaultStyles(config, themesDir);
+  copyDefaultStyles(config, resolvedTheme);
   copyStaticAssets(config);
   
   const duration = ((Date.now() - startTime) / 1000).toFixed(2);

package/lib/init.js

@@ -87,7 +87,7 @@ Welcome to my new blog! This is my first post.
 
 ## About This Site
 
-This site is built with [Sia](https://github.com/sia/sia), a simple and powerful static site generator.
+This site is built with [Sia](https://github.com/terrymooreii/sia), a simple and powerful static site generator.
 
 ## What's Next?
 
@@ -114,7 +114,7 @@ Hello! I'm ${author}. Welcome to my corner of the internet.
 
 ## About This Site
 
-This site is built with [Sia](https://github.com/sia/sia), a simple static site generator that supports:
+This site is built with [Sia](https://github.com/terrymooreii/sia), a simple static site generator that supports:
 
 - Markdown with front matter
 - Blog posts, pages, and notes
@@ -216,7 +216,7 @@ Then upload the \`dist/\` folder to any static hosting.
 
   return `# ${title}
 
-A static site built with [Sia](https://github.com/sia/sia).
+A static site built with [Sia](https://github.com/terrymooreii/sia).
 
 ## Getting Started
 

package/lib/templates.js

@@ -2,6 +2,7 @@ import nunjucks from 'nunjucks';
 import { join, dirname } from 'path';
 import { existsSync } from 'fs';
 import { fileURLToPath } from 'url';
+import { resolveTheme, getBuiltInThemesDir } from './theme-resolver.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -190,8 +191,11 @@ function createUrlFilter(basePath) {
 
 /**
  * Create and configure the Nunjucks environment
+ * 
+ * @param {object} config - Site configuration
+ * @param {object} [resolvedTheme] - Pre-resolved theme info from resolveTheme()
  */
-export function createTemplateEngine(config) {
+export function createTemplateEngine(config, resolvedTheme = null) {
   // Set up template paths - user layouts first, then defaults
   const templatePaths = [];
   
@@ -205,15 +209,18 @@ export function createTemplateEngine(config) {
     templatePaths.push(config.includesDir);
   }
   
-  // Default templates from the selected theme
+  // Resolve theme if not already resolved
   const themeName = config.theme?.name || 'main';
-  const themeDir = join(__dirname, '..', 'themes', themeName);
+  const theme = resolvedTheme || resolveTheme(themeName, config.rootDir);
+  const themeDir = theme.themeDir;
+  
+  // Add theme template paths
   templatePaths.push(join(themeDir, 'layouts'));
   templatePaths.push(join(themeDir, 'includes'));
   templatePaths.push(join(themeDir, 'pages'));
   
   // Shared includes available to all themes
-  const sharedIncludesDir = join(__dirname, '..', 'themes', '_shared', 'includes');
+  const sharedIncludesDir = join(getBuiltInThemesDir(), '_shared', 'includes');
   templatePaths.push(sharedIncludesDir);
   
   // Create the environment

package/lib/theme-resolver.js

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Built-in themes directory
+const builtInThemesDir = join(__dirname, '..', 'themes');
+
+/**
+ * Resolve the path to a theme directory
+ * 
+ * Resolution order:
+ * 1. Check built-in themes folder (sia's themes/)
+ * 2. Check for npm package sia-theme-{name}
+ * 3. Fall back to 'main' theme
+ * 
+ * @param {string} themeName - The theme name from config
+ * @param {string} rootDir - The user's project root directory
+ * @returns {{ themeDir: string, themeName: string, isExternal: boolean }}
+ */
+export function resolveTheme(themeName, rootDir = process.cwd()) {
+  // 1. Check built-in themes folder
+  const builtInThemeDir = join(builtInThemesDir, themeName);
+  if (existsSync(builtInThemeDir)) {
+    return {
+      themeDir: builtInThemeDir,
+      themeName,
+      isExternal: false
+    };
+  }
+
+  // 2. Check for npm package sia-theme-{name}
+  const packageName = `sia-theme-${themeName}`;
+  const externalThemeDir = resolveExternalTheme(packageName, rootDir);
+  
+  if (externalThemeDir) {
+    console.log(`🎨 Using external theme package: ${packageName}`);
+    return {
+      themeDir: externalThemeDir,
+      themeName,
+      isExternal: true
+    };
+  }
+
+  // 3. Fall back to 'main' theme
+  if (themeName !== 'main') {
+    console.log(`⚠️  Theme "${themeName}" not found, falling back to "main" theme`);
+  }
+  
+  return {
+    themeDir: join(builtInThemesDir, 'main'),
+    themeName: 'main',
+    isExternal: false
+  };
+}
+
+/**
+ * Attempt to resolve an external theme package
+ * 
+ * @param {string} packageName - The npm package name (sia-theme-{name})
+ * @param {string} rootDir - The user's project root directory
+ * @returns {string|null} The theme directory path or null if not found
+ */
+function resolveExternalTheme(packageName, rootDir) {
+  // First, check if the package is in the user's package.json
+  const packageJsonPath = join(rootDir, 'package.json');
+  
+  if (!existsSync(packageJsonPath)) {
+    return null;
+  }
+
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const allDeps = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies
+    };
+
+    // Check if the theme package is listed as a dependency
+    if (!allDeps[packageName]) {
+      return null;
+    }
+
+    // Try to resolve the package path
+    // Use createRequire to resolve from the user's project directory
+    const require = createRequire(join(rootDir, 'package.json'));
+    
+    try {
+      // Try to resolve the package's main entry point
+      const packageMainPath = require.resolve(packageName);
+      const packageDir = dirname(packageMainPath);
+      
+      // The theme directory is typically the package root
+      // Check if it has the expected theme structure
+      if (isValidThemeDirectory(packageDir)) {
+        return packageDir;
+      }
+      
+      // Sometimes the main entry is in a subdirectory, try parent
+      const parentDir = dirname(packageDir);
+      if (isValidThemeDirectory(parentDir)) {
+        return parentDir;
+      }
+
+      // Try node_modules directly
+      const nodeModulesPath = join(rootDir, 'node_modules', packageName);
+      if (existsSync(nodeModulesPath) && isValidThemeDirectory(nodeModulesPath)) {
+        return nodeModulesPath;
+      }
+
+      return null;
+    } catch (resolveErr) {
+      // Package might not be installed yet
+      // Try node_modules directly as fallback
+      const nodeModulesPath = join(rootDir, 'node_modules', packageName);
+      if (existsSync(nodeModulesPath) && isValidThemeDirectory(nodeModulesPath)) {
+        return nodeModulesPath;
+      }
+      return null;
+    }
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Check if a directory has the expected theme structure
+ * 
+ * @param {string} dir - Directory to check
+ * @returns {boolean}
+ */
+function isValidThemeDirectory(dir) {
+  if (!existsSync(dir)) {
+    return false;
+  }
+
+  // A valid theme must have at least layouts and pages directories
+  const hasLayouts = existsSync(join(dir, 'layouts'));
+  const hasPages = existsSync(join(dir, 'pages'));
+  
+  return hasLayouts && hasPages;
+}
+
+/**
+ * Get the built-in themes directory path
+ * 
+ * @returns {string}
+ */
+export function getBuiltInThemesDir() {
+  return builtInThemesDir;
+}
+
+/**
+ * Get list of available built-in themes
+ * 
+ * @returns {string[]}
+ */
+export function getBuiltInThemes() {
+  return readdirSync(builtInThemesDir)
+    .filter(name => {
+      if (name.startsWith('_')) return false; // Skip _shared
+      const themePath = join(builtInThemesDir, name);
+      return statSync(themePath).isDirectory();
+    });
+}
+
+export default {
+  resolveTheme,
+  getBuiltInThemesDir,
+  getBuiltInThemes
+};
+