create-trellis-docs 1.0.0

package/template/docusaurus.config.js.tpl

@@ -0,0 +1,200 @@
+// @ts-check
+import {themes as prismThemes} from 'prism-react-renderer';
+
+const path = require('path');
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: "{{projectName}}",
+  tagline: "{{tagline}}",
+  url: "{{siteUrl}}",
+  baseUrl: "/",
+  trailingSlash: true,
+  onBrokenLinks: "warn",
+  onBrokenMarkdownLinks: "warn",
+  favicon: "img/favicon.svg",
+  organizationName: "",
+  projectName: "{{projectSlug}}",
+
+  customFields: {
+    repoUrl: '{{repoUrl}}',
+  },
+
+  markdown: {
+    mermaid: true,
+  },
+
+  themes: [
+    '@docusaurus/theme-mermaid',
+    '@docusaurus/theme-live-codeblock',
+  ],
+
+  staticDirectories: ['static'],
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          breadcrumbs: true,
+          sidebarPath: './sidebars.js',
+          routeBasePath: '/',
+          path: 'docs',
+          showLastUpdateTime: true,
+          editUrl: '{{repoUrl}}/edit/main',
+        },
+        blog: {
+          showReadingTime: false,
+        },
+        theme: {
+          customCss: [
+            './src/css/tokens.css',
+            './src/css/custom.css',
+          ],
+        },
+      }),
+    ],
+  ],
+
+  plugins: [
+    '@r74tech/docusaurus-plugin-panzoom',
+    [
+      './packages/faq-index-plugin',
+      {
+        faqDir: 'docs/faq',
+        basePermalink: '/faq',
+      },
+    ],
+    function webpackPlugin(context, options) {
+      return {
+        name: 'webpack-config-plugin',
+        configureWebpack(config, isServer, utils) {
+          return {
+            resolve: {
+              extensions: ['.js', '.jsx', '.ts', '.tsx', '.json'],
+              extensionAlias: {
+                '.js': ['.js', '.jsx'],
+                '.mjs': ['.mjs', '.mjs'],
+                '.cjs': ['.cjs', '.cjs'],
+              },
+            },
+          };
+        },
+      };
+    },
+    [
+      'redirects-plugin',
+      {
+        redirectsFile: 'redirects.json'
+      }
+    ],
+    [
+      'smart-search-plugin',
+      {
+        excludedFolders: ['includes', '_includes'],
+        excludedPrefixes: ['_'],
+        searchWeights: {
+          title: 1.0,
+          'sections.heading': 1.0,
+          keywords: 0.8,
+          description: 0.6,
+          'sections.content': 0.5,
+          content: 0.4
+        }
+      }
+    ],
+    [
+      'lightbox-image-plugin',
+      {
+        selector: '.markdown img',
+        background: 'rgba(0, 0, 0, 0.8)',
+        zIndex: 999,
+        margin: 10,
+        scrollOffset: 10
+      }
+    ]
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      docs: {
+        sidebar: {
+          hideable: true,
+          autoCollapseCategories: false,
+        }
+      },
+      colorMode: {
+        defaultMode: 'dark',
+        disableSwitch: false,
+        respectPrefersColorScheme: true,
+      },
+      zoom: {
+        selectors: ['div.mermaid[data-processed="true"]', 'div.docusaurus-mermaid-container', '.drawio'],
+        wrap: true,
+        timeout: 1000,
+        toolbar: {
+          enabled: true,
+          position: 'top-right',
+          opacity: 0,
+        },
+        enableWheelZoom: true,
+        enableWheelZoomWithShift: false,
+        enableDoubleClickResetZoom: true,
+        restrictZoomOutBeyondOrigin: false,
+      },
+      metadata: [
+        { property: 'og:description', content: '{{projectName}} — {{tagline}}' },
+      ],
+      navbar: {
+        title: '{{projectName}}',
+        logo: {
+          alt: '{{projectName}} Logo',
+          src: 'img/favicon.svg',
+          className: 'header-logo',
+        },
+        items: [
+          {
+            to: '/guides/writing-docs',
+            label: 'Guides',
+            position: 'right',
+          },
+          {
+            type: 'dropdown',
+            label: 'Resources',
+            position: 'right',
+            items: [
+              {
+                to: '/blog',
+                label: 'Release Notes',
+              },
+              {
+                to: '/faq',
+                label: 'FAQs',
+              },
+            ],
+          },
+          {
+            type: 'search',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+        copyright: `\u00a9 ${new Date().getFullYear()} {{projectName}}   |   Powered by Trellis`,
+      },
+      prism: {
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula,
+      },
+    }),
+};
+
+export default config;

package/template/package.json.tpl

@@ -0,0 +1,60 @@
+{
+  "name": "{{projectSlug}}",
+  "license": "MIT",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build-tokens": "node scripts/build-tokens.js",
+    "docusaurus": "npm run build-tokens && docusaurus",
+    "start": "npm run build-tokens && docusaurus start --port 3001",
+    "build": "npm run build-tokens && docusaurus build",
+    "serve": "docusaurus serve",
+    "clear": "docusaurus clear"
+  },
+  "dependencies": {
+    "@ant-design/icons": "^5.3.7",
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/mdx-loader": "^3.9.2",
+    "@docusaurus/preset-classic": "^3.9.2",
+    "@docusaurus/theme-live-codeblock": "^3.9.2",
+    "@docusaurus/theme-mermaid": "3.9.2",
+    "@emotion/react": "^11.13.3",
+    "@emotion/styled": "^11.13.0",
+    "@mdx-js/react": "^3.1.1",
+    "@mermaid-js/layout-elk": "^0.1.9",
+    "@mui/icons-material": "^5.10.6",
+    "@mui/material": "^5.16.4",
+    "@r74tech/docusaurus-plugin-panzoom": "^2.4.0",
+    "antd": "^5.27.3",
+    "clsx": "^2.0.0",
+    "fuse.js": "^7.1.0",
+    "gray-matter": "^4.0.3",
+    "lightbox-image-plugin": "^1.0.1",
+    "mermaid": "^11.11.0",
+    "prism-react-renderer": "^2.4.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^5.3.4",
+    "redirects-plugin": "file:./packages/redirects-plugin",
+    "docusaurus-plugin-faq-index": "file:./packages/faq-index-plugin",
+    "smart-search-plugin": "^3.1.1",
+    "webpack": "^5.104.1",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/types": "3.9.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  }
+}

package/template/packages/faq-index-plugin/README.md

@@ -0,0 +1,104 @@
+# FAQ Index Plugin for Docusaurus
+
+A Docusaurus 3.x local plugin that scans `/docs/faq/*.mdx` at build time, extracts questions from `###` headings, and exposes the full FAQ index via `setGlobalData`. Designed to work with the `FaqTableOfContents` component.
+
+## Features
+
+- 🔍 Auto-discovery of FAQ files in `docs/faq/`
+- 📋 Extracts questions from `###` headings with frontmatter parsing
+- 🔗 Generates deep-link anchors matching Docusaurus conventions
+- 📦 Exposes data via `useGlobalData` for client-side components
+
+## Installation
+
+This is a local plugin included in the project under `packages/`. No separate installation is needed, but ensure `gray-matter` is available:
+
+```bash
+cd packages/faq-index-plugin
+yarn install
+```
+
+## Configuration
+
+Add the plugin to `docusaurus.config.js`:
+
+```javascript
+module.exports = {
+  plugins: [
+    [
+      './packages/faq-index-plugin',
+      {
+        faqDir: 'docs/faq',        // path relative to site root
+        basePermalink: '/faq',     // base URL path for FAQ pages
+      },
+    ],
+  ],
+};
+```
+
+## Plugin options
+
+| Option          | Type     | Default      | Description                                      |
+|-----------------|----------|--------------|--------------------------------------------------|
+| `faqDir`        | `string` | `'docs/faq'` | Path to the FAQ folder relative to the site root. |
+| `basePermalink` | `string` | `'/faq'`     | Base permalink for generated FAQ links.           |
+
+## How it works
+
+1. At build time, the plugin reads every `.mdx` and `.md` file in the configured FAQ directory (excluding `index.mdx` and `index.md`).
+2. It parses each file's frontmatter for `title` and `description` using `gray-matter`.
+3. It extracts question text from every `###` heading, stripping bold, italic, inline code, and link formatting.
+4. The full index is sorted alphabetically by topic title and exposed via Docusaurus `setGlobalData`.
+5. The `FaqTableOfContents` component reads this data at runtime using `useGlobalData`.
+
+## Expected FAQ file format
+
+Each topic file should use `###` headings for questions:
+
+```mdx
+---
+title: Secrets
+description: Managing secrets, vaults, and credential rotation.
+---
+
+# Secrets
+
+### How do I add a secret to my application?
+
+Answer content here...
+
+### How do I rotate a secret?
+
+Answer content here...
+```
+
+## Anchor generation
+
+The plugin generates anchors from heading text using the same convention as Docusaurus: lowercase, special characters stripped, spaces replaced with hyphens. Deep links align automatically with Docusaurus-rendered anchors unless you use custom heading IDs (e.g., `### My heading {#custom-id}`).
+
+## File structure
+
+```
+your-docusaurus-project/
+├── docs/
+│   └── faq/
+│       ├── index.mdx
+│       ├── authentication-permissions.mdx
+│       ├── database-infrastructure.mdx
+│       └── secrets.mdx
+├── packages/
+│   └── faq-index-plugin/
+│       ├── package.json
+│       ├── index.js
+│       └── README.md
+├── src/
+│   └── components/
+│       └── FaqTableOfContents/
+│           ├── index.jsx
+│           └── styles.module.css
+└── docusaurus.config.js
+```
+
+## License
+
+MIT

package/template/packages/faq-index-plugin/index.js

@@ -0,0 +1,91 @@
+// packages/faq-index-plugin/index.js
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+
+const PLUGIN_NAME = 'docusaurus-plugin-faq-index';
+
+module.exports = function faqIndexPlugin(context, options) {
+  const opts = options || {};
+  const faqDir = path.resolve(context.siteDir, opts.faqDir || 'docs/faq');
+  const basePermalink = opts.basePermalink || '/faq';
+
+  return {
+    name: PLUGIN_NAME,
+
+    async loadContent() {
+      if (!fs.existsSync(faqDir)) {
+        console.warn(`[${PLUGIN_NAME}] FAQ directory not found: ${faqDir}`);
+        return [];
+      }
+
+      const files = fs
+        .readdirSync(faqDir)
+        .filter((f) => /\.(mdx?)$/.test(f) && f !== 'index.mdx' && f !== 'index.md');
+
+      const topics = [];
+
+      for (const file of files) {
+        const filePath = path.join(faqDir, file);
+
+        let raw;
+        try {
+          raw = fs.readFileSync(filePath, 'utf-8');
+        } catch (err) {
+          console.warn(`[${PLUGIN_NAME}] Could not read ${filePath}:`, err.message);
+          continue;
+        }
+
+        const { data: frontmatter, content } = matter(raw);
+
+        const slug = file.replace(/\.mdx?$/, '');
+        const title =
+          frontmatter.title ||
+          slug
+            .replace(/-/g, ' ')
+            .replace(/\b\w/g, (c) => c.toUpperCase());
+
+        // Extract questions from ### headings
+        const h3Regex = /^###\s+(.+)$/gm;
+        const questions = [];
+        let match;
+
+        while ((match = h3Regex.exec(content)) !== null) {
+          let questionText = match[1]
+            .trim()
+            .replace(/\*{1,3}(.*?)\*{1,3}/g, '$1')
+            .replace(/`([^`]+)`/g, '$1')
+            .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+            .trim();
+
+          if (questionText) {
+            const anchor = questionText
+              .toLowerCase()
+              .replace(/[^\w\s-]/g, '')
+              .replace(/\s+/g, '-')
+              .replace(/-+/g, '-');
+
+            questions.push({ text: questionText, anchor });
+          }
+        }
+
+        topics.push({
+          slug,
+          title,
+          description: frontmatter.description || '',
+          permalink: `${basePermalink}/${slug}`,
+          questions,
+        });
+      }
+
+      topics.sort((a, b) => a.title.localeCompare(b.title));
+      return topics;
+    },
+
+    async contentLoaded({ content, actions }) {
+      const { setGlobalData } = actions;
+      setGlobalData({ topics: content || [] });
+    },
+  };
+};

package/template/packages/faq-index-plugin/package.json

@@ -0,0 +1,15 @@
+{
+    "name": "faq-index-plugin",
+    "version": "1.0.0",
+    "description": "A custom Docusaurus plugin that indexes FAQ questions from docs/faq/ at build time",
+    "main": "index.js",
+    "author": "Patricia McPhee",
+    "license": "MIT",
+    "peerDependencies": {
+      "@docusaurus/core": "3.9.2",
+      "react": "^19.0.0"
+    },
+    "dependencies": {
+      "gray-matter": "^4.0.3"
+    }
+  }

package/template/packages/redirects-plugin/README.md

@@ -0,0 +1,186 @@
+# Redirects Plugin for Docusaurus
+
+A Docusaurus 3.x plugin that handles URL redirects by generating static HTML redirect pages during the build process.
+
+## Features
+
+- 🔄 Create client-side redirects using meta refresh and JavaScript
+- 📁 Support for multiple redirect configuration sources
+- 🎯 Handles both file-based (`/path.html`) and directory-based (`/path/index.html`) redirects
+- 🔍 Auto-detection of redirect configuration files
+- ⚡ Zero runtime overhead - generates static HTML files
+
+## Installation
+
+This is a local plugin included in the project. No separate installation needed.
+
+## Configuration
+
+Add the plugin to your `docusaurus.config.js`:
+
+```javascript
+module.exports = {
+  plugins: [
+    [
+      './packages/redirects-plugin',
+      {
+        // Optional: specify redirects directly in config
+        redirects: [
+          {
+            from: '/old-page',
+            to: '/new-page',
+            type: 301 // optional, defaults to 301
+          }
+        ],
+        // Optional: specify a custom redirects file location
+        redirectsFile: 'config/redirects.json'
+      }
+    ]
+  ]
+};
+```
+
+## Redirect Configuration Sources
+
+The plugin loads redirects from multiple sources in this order:
+
+### 1. Plugin Options
+
+Define redirects directly in `docusaurus.config.js`:
+
+```javascript
+{
+  redirects: [
+    { from: '/old', to: '/new' },
+    { from: '/legacy/path', to: '/modern/path', type: 302 }
+  ]
+}
+```
+
+### 2. Custom File Location
+
+Specify a custom file path:
+
+```javascript
+{
+  redirectsFile: 'config/my-redirects.json'
+}
+```
+
+### 3. Auto-Detection
+
+If no `redirectsFile` is specified, the plugin automatically looks for:
+
+- `redirects.json` (project root)
+- `config/redirects.json`
+- `src/redirects.json`
+
+## Redirects File Format
+
+Create a `redirects.json` file:
+
+```json
+[
+  {
+    "from": "/old-docs/getting-started",
+    "to": "/docs/introduction"
+  },
+  {
+    "from": "/api-v1",
+    "to": "/api/v2",
+    "type": 302
+  },
+  {
+    "from": "/blog/old-post",
+    "to": "https://external-site.com/new-post"
+  }
+]
+```
+
+## Redirect Object Properties
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `from` | string | Yes | - | Source path to redirect from |
+| `to` | string | Yes | - | Destination URL or path |
+| `type` | number | No | 301 | HTTP redirect status code |
+
+## How It Works
+
+1. During the build process, the plugin reads all configured redirects
+2. For each redirect, it generates HTML files with:
+   - Meta refresh tag for immediate redirect
+   - JavaScript fallback for better compatibility
+   - Canonical link tag for SEO
+3. Creates both `/path.html` and `/path/index.html` for maximum compatibility
+
+## Generated HTML Example
+
+For a redirect from `/old` to `/new`, the plugin generates:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="refresh" content="0; url=/new">
+    <link rel="canonical" href="/new" />
+    <title>Redirecting...</title>
+  </head>
+  <body>
+    <p>Redirecting to <a href="/new">/new</a>...</p>
+    <script>
+      window.location.href = '/new';
+    </script>
+  </body>
+</html>
+```
+
+## Path Normalization
+
+- Leading slashes are added if missing
+- Trailing slashes are removed for consistency
+- Hash fragments are preserved
+- External URLs (starting with `http`) are supported
+
+## Debugging
+
+The plugin logs its activity during the build:
+
+```
+Loaded 5 redirects from config
+Auto-detected and loaded 10 redirects from redirects.json
+Processing 15 redirects...
+Created redirect: /old → /new (301)
+```
+
+## Common Use Cases
+
+- Maintaining URLs after site restructuring
+- Redirecting from legacy documentation versions
+- Creating short URLs for marketing campaigns
+- Handling moved or renamed pages
+- Redirecting to external resources
+
+## Limitations
+
+- Redirects only work for paths that don't correspond to actual files
+- Server-side redirects are more efficient but require server configuration
+- Meta refresh redirects may not preserve HTTP referrer information
+
+## Troubleshooting
+
+**Redirects not working:**
+
+- Check that the source path doesn't conflict with an existing page
+- Verify the JSON file is valid (use a JSON validator)
+- Check build logs for error messages
+
+**Invalid redirect warnings:**
+
+- Ensure both `from` and `to` fields are present
+- Check for typos in field names
+
+## License
+
+MIT