A modern static documentation website for plugin documentation with automatic GitHub integration, built with Next.js and Fumadocs. Optimized for GitHub Pages deployment with automated CI/CD.

• 📚 Plugin Documentation: Automatically fetch and display documentation from GitHub repositories
• 🏷️ Version Management: Support multiple versions mapped to different GitHub branches
• 🔍 Full-Text Search: Powered by Orama for fast documentation search
• 🌙 Theme Toggle: Light/dark mode support
• 📱 Responsive Design: Mobile-friendly layout
• 🚀 Static Export: Optimized for GitHub Pages deployment
• 🔄 Auto Deployment: GitHub Actions workflow for continuous deployment
• 💾 Smart Caching: Intelligent caching system for GitHub API calls

• Node.js 18+ or higher
• npm or pnpm
• GitHub Personal Access Token (optional, but recommended)

# Clone the repository git clone <your-repository-url> cd plugin-doc-site # Install dependencies npm install

To avoid GitHub API rate limits (60 requests/hour for unauthenticated users vs 5000/hour with a token), create a .env.local file:

1. Create a Personal Access Token (PAT) on GitHub: Settings > Developer settings > PAT (No special scopes needed for public repos).
2. Create GITHUB_TOKEN in .env.local file:

   GITHUB_TOKEN=your_token_here

This pulls the documentation MD/MDX files from the configured GitHub repositories.

# Online: Fetch fresh content from GitHub npm run fetch-docs # Offline/Cached: Use local cache only (no API calls) npm run fetch-docs:cache

Since GitHub Actions may hit API limits easily, we recommend building locally and pushing the static site.

1. Build locally: This generates the out/ folder.

   npm run build # (Check for errors locally)

2. Commit and Push:

   git add . git commit -m "Update docs" git push origin main

npm install 

or

pnpm install 

Create a .env.local file in the root directory:

GITHUB_TOKEN=your_github_personal_access_token_here NEXT_PUBLIC_SITE_URL=http://localhost:3000

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a descriptive name like "Plugin Docs Site"
4. Select scopes:
   • public_repo (for public repositories)
   • repo (if you need access to private repositories)
5. Copy the generated token and add it to your .env.local file

Note: GitHub token is optional for public repositories, but recommended to avoid rate limiting.

npm run dev

Open http://localhost:3001 in your browser.

# Build with fresh documentation fetch npm run build # Or build with cached documentation (faster) npm run build:cache

static-plugin-doc-site-3/ ├── .github/ │ └── workflows/ │ └── deploy.yml # GitHub Actions deployment workflow ├── app/ # Next.js app directory │ ├── (home)/ # Homepage with plugin/product listings │ ├── docs/ # Documentation pages │ │ ├── [[...slug]]/ # Dynamic documentation routes │ │ └── components/ # Docs-specific components │ ├── api/ # API routes (search, etc.) │ └── llms-full.txt/ # LLM-optimized documentation ├── components/ # Shared React components │ ├── partials/ # Reusable partial components │ └── provider.tsx # Theme and context providers ├── content/docs/ # Generated documentation (auto-created) │ ├── [plugin-name]/ │ │ ├── _meta.json # Navigation structure │ │ └── [version]/ │ │ └── overview.mdx # Version documentation ├── lib/ │ ├── config.ts # **Plugin/product configuration (EDIT THIS)** │ ├── source.ts # Fumadocs source configuration │ └── layout.shared.tsx # Shared layout configuration ├── public/ # Static assets │ └── images/ # Plugin images and assets ├── scripts/ │ └── fetch-docs.ts # Documentation fetcher script ├── next.config.mjs # Next.js configuration ├── source.config.ts # MDX configuration └── package.json # Dependencies and scripts 

Edit lib/config.ts and add your plugin to the plugins array:

export const config: Config = { plugins: [ { id: "your-plugin-slug", title: "Your Plugin Name", description: "Brief description of what your plugin does", repo: "your-github-username/your-repo-name", latestVersion: "3.x", versions: [ { version: "1.x", github_branch: "1.x", limited_files: [ { name: "README.md", title: "Overview", slug: "overview" }, ], }, { version: "2.x", github_branch: "2.x", limited_files: [ { name: "README.md", title: "Overview", slug: "overview" }, ], }, { version: "3.x", github_branch: "3.x", limited_files: [ { name: "README.md", title: "Overview", slug: "overview" }, ], }, ], }, // Add more plugins... ], products: [ // Your products here... ], };

• id (required): Unique identifier, used in URLs (e.g., /docs/filament-tree/3.x/overview)
• title (required): Display name shown in the UI
• description (required): Short description for the plugin card
• repo (required): GitHub repository in format owner/repo
• latestVersion (required): The default version shown to users
• versions (required): Array of version configurations
  • version: Version identifier (e.g., '1.x', '2.x')
  • github_branch: Branch name in GitHub repository
  • limited_files: Array of specific files to fetch (usually just README.md for overview)
• hidden (optional): Set to true to hide from the homepage
• is_manual (optional): Set to true for custom documentation structure
• docs_structure (optional): 'folder_based' for complex structures
• docs_path (optional): Custom path in repo for documentation
• sections (optional): Manual section definitions for complex docs

Products are external links shown alongside plugins on the homepage:

products: [ { id: "your-product-id", title: "Your Product Name", description: "What your product does", link: "https://yourproduct.com", badge: { text: "External", color: "green", }, }, ];

For plugins with multiple documentation files organized in folders:

{ id: 'complex-plugin', title: 'Complex Plugin', description: 'Plugin with structured documentation', repo: 'owner/repo', latestVersion: '3.x', is_manual: true, docs_structure: 'folder_based', docs_path: 'docs', // Path within the repository versions: [ { version: '3.x', github_branch: 'main' } ], sections: [ { name: 'Getting Started', slug: 'getting-started', files: [ { name: 'installation.md', title: 'Installation', slug: 'installation' }, { name: 'configuration.md', title: 'Configuration', slug: 'configuration' }, ], }, { name: 'Advanced', slug: 'advanced', files: [ { name: 'customization.md', title: 'Customization', slug: 'customization' }, ], }, ], }

1. Push your code to GitHub:

   git add . git commit -m "Initial commit" git push origin main

2. Enable GitHub Pages:

   • Go to your repository on GitHub
   • Navigate to Settings → Pages
   • Under "Build and deployment"
   • Source: Select "GitHub Actions"

3. Set GitHub Token (Optional):

   • Only needed if fetching from private repositories
   • Go to Settings → Secrets and variables → Actions
   • Add a new repository secret named GITHUB_TOKEN
   • Use a Personal Access Token with repo scope

4. Configure Base Path (if needed):

   • The workflow automatically detects your repository name
   • Your site will be at: https://[username].github.io/[repository-name]/
   • To customize, set NEXT_PUBLIC_BASE_PATH environment variable

The GitHub Actions workflow automatically:

• ✅ Triggers on every push to main branch
• ✅ Fetches latest documentation from configured repos
• ✅ Builds the static site
• ✅ Deploys to GitHub Pages

You can also trigger deployment manually:

1. Go to Actions tab in your repository
2. Select "Deploy to GitHub Pages" workflow
3. Click "Run workflow"

To rebuild docs without code changes:

# Locally trigger a repository dispatch event curl -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token YOUR_GITHUB_TOKEN" \ https://api.github.com/repos/YOUR_USERNAME/YOUR_REPO/dispatches \ -d '{"event_type":"rebuild-docs"}'

# Development npm run dev # Start development server on port 3001 # Building npm run build # Fetch docs and build for production npm run build:cache # Build using cached documentation (faster) npm run build:static # Build for static export (used by GitHub Actions) # Documentation Management npm run fetch-docs # Fetch documentation from GitHub npm run fetch-docs:cache # Use cached docs, skip GitHub fetch # Type Checking npm run types:check # Run TypeScript type checking # Preview Production Build npm run start # Serve the production build locally

Causes:

• README.md doesn't exist in the specified GitHub repository/branch
• GitHub token lacks proper permissions
• Branch name doesn't match configuration

Solutions:

1. Verify the file exists: https://github.com/[owner]/[repo]/blob/[branch]/README.md
2. Check your GitHub token has access to the repository
3. Ensure github_branch in lib/config.ts matches the actual branch name
4. Run npm run fetch-docs to see detailed error messages

Cause: GitHub API rate limiting (60 requests/hour without token, 5000 with token)

Solutions:

1. Add a GitHub token to .env.local
2. Use cached documentation: npm run build:cache
3. Wait for the rate limit to reset (check headers in error)

Solutions:

1. Delete node_modules and reinstall: rm -rf node_modules && npm install
2. Clear Next.js cache: rm -rf .next
3. Ensure all dependencies are installed: npm install

Causes:

• Images not in public/images/ directory
• Incorrect image paths in markdown
• Base path not configured correctly

Solutions:

1. Ensure images are in public/images/[plugin-name]/
2. Use relative paths in markdown: ![alt](./image.png)
3. Check basePath configuration in next.config.mjs

Common issues:

1. Permissions error:

   • Go to Settings → Actions → General
   • Scroll to "Workflow permissions"
   • Select "Read and write permissions"

2. Pages not enabled:

   • Go to Settings → Pages
   • Set source to "GitHub Actions"

3. Build errors:

   • Check the Actions tab for detailed logs
   • Ensure all required files exist in repository
   • Verify lib/config.ts is correctly formatted

Solutions:

# Clear all caches rm -rf .next .cache node_modules/.cache # Rebuild npm run build

Enable verbose logging by checking:

1. Browser console for client-side errors
2. Terminal output for build-time errors
3. .cache/ directory for fetched files

1. Check the Fumadocs documentation
2. Review GitHub Actions logs in the Actions tab
3. Inspect .cache/raw/ to see fetched files
4. Enable debug mode by adding console.log statements in scripts/fetch-docs.ts

Update site colors in app/global.css:

:root { --primary: 220 90% 56%; --primary-foreground: 0 0% 100%; /* Modify other colors as needed */ }

Update navigation in lib/layout.shared.tsx:

export const baseOptions: HomeLayoutProps = { nav: { title: "Your Site Name", }, links: [ // Add custom navigation links ], };

Customize MDX components in mdx-components.tsx:

export function useMDXComponents(components: MDXComponents): MDXComponents { return { ...components, // Add custom component overrides }; }

Create new pages in the app/ directory following Next.js conventions.

This project is open source. Please check the repository for license details.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Test locally: npm run build && npm run start
5. Commit changes: git commit -m "Add your feature"
6. Push to branch: git push origin feature/your-feature
7. Submit a pull request

Built with ❤️ using Next.js and Fumadocs

npm run dev

npm run types:check

npm run build

npm run start

 ## Contributing 1. Add new plugins/products to `lib/config.ts` 2. Test locally with `npm run dev` 3. Ensure build passes with `npm run build` 4. Commit and push changes ## License [Add your license here]