create-trellis-docs 1.0.0

package/bin/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const { init } = require('../lib/index');
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('create-trellis-docs')
+  .version(pkg.version)
+  .description('Create a new Trellis documentation site')
+  .argument('[project-name]', 'Name of the project directory')
+  .option('-s, --skip-install', 'Skip dependency installation')
+  .option(
+    '-p, --package-manager <pm>',
+    'Package manager to use (npm, yarn, pnpm)',
+    'yarn'
+  )
+  .action(async (projectName, options) => {
+    try {
+      await init(projectName, options);
+    } catch (err) {
+      console.error('\nError:', err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/lib/index.js

@@ -0,0 +1,178 @@
+const path = require('path');
+const fs = require('fs-extra');
+const prompts = require('prompts');
+const spawn = require('cross-spawn');
+
+const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
+
+function toSlug(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+async function promptForMissing(projectName) {
+  const questions = [];
+
+  if (!projectName) {
+    questions.push({
+      type: 'text',
+      name: 'projectName',
+      message: 'Project name:',
+      initial: 'my-docs',
+      validate: (val) =>
+        /^[a-z0-9][a-z0-9-]*$/.test(val) || 'Use lowercase letters, numbers, and hyphens',
+    });
+  }
+
+  questions.push(
+    {
+      type: 'text',
+      name: 'title',
+      message: 'Site title:',
+      initial: 'My Docs',
+    },
+    {
+      type: 'text',
+      name: 'tagline',
+      message: 'Tagline:',
+      initial: 'Documentation powered by Trellis',
+    },
+    {
+      type: 'text',
+      name: 'siteUrl',
+      message: 'Site URL:',
+      initial: 'https://example.com',
+    },
+    {
+      type: 'text',
+      name: 'repoUrl',
+      message: 'GitHub repo URL (optional):',
+      initial: '',
+    }
+  );
+
+  const answers = await prompts(questions, {
+    onCancel: () => {
+      console.log('\nScaffolding cancelled.');
+      process.exit(0);
+    },
+  });
+
+  return {
+    projectName: projectName || answers.projectName,
+    title: answers.title,
+    tagline: answers.tagline,
+    siteUrl: answers.siteUrl,
+    repoUrl: answers.repoUrl,
+  };
+}
+
+function processTemplate(content, vars) {
+  return content
+    .replace(/\{\{projectName\}\}/g, vars.title)
+    .replace(/\{\{projectSlug\}\}/g, vars.projectSlug)
+    .replace(/\{\{tagline\}\}/g, vars.tagline)
+    .replace(/\{\{siteUrl\}\}/g, vars.siteUrl)
+    .replace(/\{\{repoUrl\}\}/g, vars.repoUrl);
+}
+
+async function copyTemplate(destDir, vars) {
+  const SKIP = new Set(['node_modules', '.docusaurus', 'build']);
+
+  async function copyDir(src, dest) {
+    await fs.ensureDir(dest);
+    const entries = await fs.readdir(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (SKIP.has(entry.name)) continue;
+
+      const srcPath = path.join(src, entry.name);
+      const destName = entry.name === '_gitignore' ? '.gitignore' : entry.name;
+
+      if (entry.isDirectory()) {
+        await copyDir(srcPath, path.join(dest, destName));
+      } else if (entry.name.endsWith('.tpl')) {
+        // Template file — process placeholders and strip .tpl extension
+        const content = await fs.readFile(srcPath, 'utf-8');
+        const processed = processTemplate(content, vars);
+        const finalName = destName.replace(/\.tpl$/, '');
+        await fs.writeFile(path.join(dest, finalName), processed);
+      } else {
+        await fs.copy(srcPath, path.join(dest, destName));
+      }
+    }
+  }
+
+  await copyDir(TEMPLATE_DIR, destDir);
+}
+
+function installDeps(projectDir, packageManager) {
+  console.log(`\nInstalling dependencies with ${packageManager}...\n`);
+
+  const result = spawn.sync(packageManager, ['install'], {
+    cwd: projectDir,
+    stdio: 'inherit',
+  });
+
+  if (result.status !== 0) {
+    console.error(
+      `\nDependency installation failed. Run "${packageManager} install" manually in the project directory.`
+    );
+    return false;
+  }
+
+  return true;
+}
+
+async function init(projectName, options = {}) {
+  console.log('\n  Trellis — Create a new documentation site\n');
+
+  const vars = await promptForMissing(projectName);
+  vars.projectSlug = toSlug(vars.projectName);
+
+  const destDir = path.resolve(process.cwd(), vars.projectName);
+
+  if (await fs.pathExists(destDir)) {
+    const contents = await fs.readdir(destDir);
+    if (contents.length > 0) {
+      throw new Error(`Directory "${vars.projectName}" already exists and is not empty.`);
+    }
+  }
+
+  console.log(`\nScaffolding project in ${destDir}...\n`);
+
+  await copyTemplate(destDir, vars);
+
+  console.log('Project files created.');
+
+  // Initialize git repo (required for showLastUpdateTime)
+  console.log('Initializing git repository...');
+  spawn.sync('git', ['init'], { cwd: destDir, stdio: 'ignore' });
+  spawn.sync('git', ['add', '-A'], { cwd: destDir, stdio: 'ignore' });
+  spawn.sync('git', ['commit', '-m', 'Initial commit from create-trellis-docs'], {
+    cwd: destDir,
+    stdio: 'ignore',
+  });
+  console.log('Git repository initialized.');
+
+  if (!options.skipInstall) {
+    const pm = options.packageManager || 'yarn';
+    installDeps(destDir, pm);
+  }
+
+  console.log(`
+  Done! Your Trellis docs site is ready.
+
+  Next steps:
+
+    cd ${vars.projectName}
+    ${options.skipInstall ? (options.packageManager || 'yarn') + ' install\n    ' : ''}${options.packageManager || 'yarn'} start
+
+  Your site will be available at http://localhost:3001
+`);
+}
+
+module.exports = { init };

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "create-trellis-docs",
+  "version": "1.0.0",
+  "description": "Create a new Trellis documentation site",
+  "license": "MIT",
+  "bin": {
+    "create-trellis-docs": "bin/index.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "cross-spawn": "^7.0.3",
+    "fs-extra": "^11.0.0",
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+build/
+.docusaurus/
+src/css/tokens.css
+.env
+*.log

package/template/blog/2025-01-01-welcome.md

@@ -0,0 +1,15 @@
+---
+title: Welcome
+description: Welcome to our documentation site.
+slug: welcome
+authors:
+  - name: Team
+---
+
+Welcome to our documentation site! This is a starter blog post.
+
+<!-- truncate -->
+
+## Getting Started
+
+Check out the [Getting Started](/getting-started/) guide to learn about the features available in your documentation site.

package/template/design-tokens.json

@@ -0,0 +1,218 @@
+{
+  "neutral": {
+    "white": {
+      "value": "#ffffff",
+      "type": "color"
+    },
+    "slate-50": {
+      "value": "#f8fafc",
+      "type": "color"
+    },
+    "slate-100": {
+      "value": "#f1f5f9",
+      "type": "color"
+    },
+    "slate-200": {
+      "value": "#e2e8f0",
+      "type": "color"
+    },
+    "slate-300": {
+      "value": "#cbd5e1",
+      "type": "color"
+    },
+    "slate-400": {
+      "value": "#94a3b8",
+      "type": "color"
+    },
+    "slate-500": {
+      "value": "#64748b",
+      "type": "color"
+    },
+    "slate-600": {
+      "value": "#475569",
+      "type": "color"
+    },
+    "slate-700": {
+      "value": "#334155",
+      "type": "color"
+    },
+    "slate-800": {
+      "value": "#1e293b",
+      "type": "color"
+    },
+    "slate-900": {
+      "value": "#0f172a",
+      "type": "color"
+    }
+  },
+  "brand": {
+    "primary-50": {
+      "value": "#f5f3ff",
+      "type": "color"
+    },
+    "primary-100": {
+      "value": "#ede9fe",
+      "type": "color"
+    },
+    "primary-200": {
+      "value": "#ddd6fe",
+      "type": "color"
+    },
+    "primary-300": {
+      "value": "#c4b5fd",
+      "type": "color"
+    },
+    "primary-400": {
+      "value": "#a78bfa",
+      "type": "color"
+    },
+    "primary-500": {
+      "value": "#8b5cf6",
+      "type": "color"
+    },
+    "primary-600": {
+      "value": "#7c3aed",
+      "type": "color"
+    },
+    "primary-700": {
+      "value": "#6d28d9",
+      "type": "color"
+    },
+    "primary-800": {
+      "value": "#5b21b6",
+      "type": "color"
+    },
+    "primary-900": {
+      "value": "#4c1d95",
+      "type": "color"
+    }
+  },
+  "utility": {
+    "green-20": {
+      "value": "#dcfce7",
+      "type": "color"
+    },
+    "green-100": {
+      "value": "#16a34a",
+      "type": "color"
+    },
+    "red-20": {
+      "value": "#fee2e2",
+      "type": "color"
+    },
+    "red-100": {
+      "value": "#dc2626",
+      "type": "color"
+    },
+    "yellow-20": {
+      "value": "#fef9c3",
+      "type": "color"
+    },
+    "yellow-100": {
+      "value": "#eab308",
+      "type": "color"
+    }
+  },
+  "accent": {
+    "teal-200": {
+      "value": "#99f6e4",
+      "type": "color"
+    },
+    "teal-300": {
+      "value": "#5eead4",
+      "type": "color"
+    },
+    "teal-400": {
+      "value": "#2dd4bf",
+      "type": "color"
+    },
+    "teal-500": {
+      "value": "#14b8a6",
+      "type": "color"
+    },
+    "teal-600": {
+      "value": "#0d9488",
+      "type": "color"
+    }
+  },
+  "spacing": {
+    "spacing-8": {
+      "value": "8px",
+      "type": "spacing"
+    },
+    "spacing-16": {
+      "value": "16px",
+      "type": "spacing"
+    },
+    "spacing-24": {
+      "value": "24px",
+      "type": "spacing"
+    },
+    "spacing-32": {
+      "value": "32px",
+      "type": "spacing"
+    },
+    "spacing-40": {
+      "value": "40px",
+      "type": "spacing"
+    },
+    "spacing-48": {
+      "value": "48px",
+      "type": "spacing"
+    },
+    "spacing-64": {
+      "value": "64px",
+      "type": "spacing"
+    },
+    "spacing-80": {
+      "value": "80px",
+      "type": "spacing"
+    },
+    "spacing-96": {
+      "value": "96px",
+      "type": "spacing"
+    },
+    "spacing-120": {
+      "value": "120px",
+      "type": "spacing"
+    }
+  },
+  "border-radius": {
+    "border-radius-4": {
+      "value": "4px",
+      "type": "borderRadius"
+    },
+    "border-radius-8": {
+      "value": "8px",
+      "type": "borderRadius"
+    },
+    "border-radius-30": {
+      "value": "30px",
+      "type": "borderRadius"
+    },
+    "border-radius-900": {
+      "value": "900px",
+      "type": "borderRadius"
+    }
+  },
+  "border-width": {
+    "border-width-1": {
+      "value": "1px",
+      "type": "borderWidth"
+    },
+    "border-width-2": {
+      "value": "2px",
+      "type": "borderWidth"
+    },
+    "border-width-none": {
+      "value": "0px",
+      "type": "borderWidth"
+    }
+  },
+  "typography": {
+    "fontFamily": {
+      "name": "font-family",
+      "value": "'Segoe UI', 'SF Pro Display', system-ui, -apple-system, sans-serif"
+    }
+  }
+}

package/template/docs/faq/general.mdx

@@ -0,0 +1,16 @@
+---
+title: General
+description: General questions.
+---
+
+### How do I add a new page?
+
+Create a new `.mdx` file in the `docs/` directory. Add it to `sidebars.js` to include it in the sidebar navigation. The page will be available at a URL matching its file path.
+
+### How do I customize the colors?
+
+Edit `design-tokens.json` at the project root. Run `yarn build-tokens` to regenerate the CSS, or simply `yarn start` which runs it automatically.
+
+### How does the search work?
+
+The smart search plugin indexes all documentation at build time. Search is performed client-side using Fuse.js for fast, fuzzy matching. You can configure field weights in `docusaurus.config.js`.

package/template/docs/faq/index.mdx

@@ -0,0 +1,13 @@
+---
+title: Frequently Asked Questions
+id: faq
+slug: /faq
+description: Common questions about this documentation site.
+hide_table_of_contents: true
+---
+
+import FaqTableOfContents from '@site/src/components/FaqTableOfContents';
+
+Browse frequently asked questions below, or use the search to find answers.
+
+<FaqTableOfContents />

package/template/docs/getting-started.mdx

@@ -0,0 +1,54 @@
+---
+title: Getting Started
+description: Get up and running with your documentation site.
+keywords: [getting-started, setup, introduction]
+---
+
+Welcome to your new documentation site, built with [Trellis](https://trellis.pixlngrid.com) — an opinionated docs framework on Docusaurus.
+
+## Quick Start
+
+```bash
+# Start the dev server
+yarn start
+```
+
+:::tip
+The dev server runs on port 3001 by default. Visit `http://localhost:3001` to see your docs.
+:::
+
+## Project Structure
+
+```
+your-project/
+├── docs/              # Your documentation content
+├── blog/              # Release notes and blog posts
+├── src/
+│   ├── css/           # Custom CSS and design tokens
+│   ├── theme/         # Customized Docusaurus theme components
+│   ├── components/    # Reusable React components
+│   └── pages/         # Custom pages (homepage)
+├── static/            # Static assets (images, fonts)
+├── packages/          # Local plugins
+│   ├── redirects-plugin/
+│   └── faq-index-plugin/
+├── design-tokens.json # Design token definitions
+└── docusaurus.config.js
+```
+
+## What's Included
+
+- **Custom theme** with last-updated date at the top of each page, heading copy-to-clipboard, pill-style tabs, and custom admonition icons
+- **Design token system** that converts `design-tokens.json` into CSS custom properties
+- **Smart search** with Fuse.js — no external service required
+- **Image lightbox** — click-to-zoom on any image
+- **Mermaid diagrams** with pan and zoom support
+- **FAQ index plugin** — auto-generates FAQ table of contents
+- **Redirect management** via `redirects.json`
+
+## Next Steps
+
+- Edit this page at `docs/getting-started.mdx`
+- Add new docs to the `docs/` directory
+- Customize your brand colors in `design-tokens.json`
+- Update site metadata in `docusaurus.config.js`

package/template/docs/guides/writing-docs.mdx

@@ -0,0 +1,90 @@
+---
+title: Writing Docs
+description: Supported markdown features and content authoring guide.
+keywords: [writing, markdown, authoring]
+---
+
+This guide covers the markdown features available in your Trellis documentation site.
+
+## Headings
+
+Use standard markdown headings (`##`, `###`, `####`). Each heading automatically gets an anchor link with a copy-to-clipboard button on hover.
+
+## Code Blocks
+
+Fenced code blocks support syntax highlighting via Prism:
+
+```javascript title="example.js"
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+## Admonitions
+
+:::note
+This is a **note** admonition. Use it for supplementary information.
+:::
+
+:::tip
+This is a **tip** admonition. Use it for best practices.
+:::
+
+:::info
+This is an **info** admonition. Use it for important context.
+:::
+
+:::caution
+This is a **caution** admonition. Use it for things that could cause issues.
+:::
+
+:::danger
+This is a **danger** admonition. Use it for critical warnings.
+:::
+
+## Tabs
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+
+```bash
+npm install
+```
+
+  </TabItem>
+  <TabItem value="yarn" label="yarn">
+
+```bash
+yarn install
+```
+
+  </TabItem>
+</Tabs>
+
+## Tables
+
+| Feature | Status |
+|---------|--------|
+| Smart Search | Available |
+| Image Lightbox | Available |
+| Mermaid Diagrams | Available |
+
+## Mermaid Diagrams
+
+```mermaid
+graph LR
+    A[Write Content] --> B[Build]
+    B --> C[Deploy]
+```
+
+## Collapsible Sections
+
+<details>
+  <summary>Click to expand</summary>
+
+  This content is hidden by default.
+
+</details>