{"id":35725558,"url":"https://github.com/osodevops/docusaurus-llm-docs","last_synced_at":"2026-04-04T03:06:15.498Z","repository":{"id":332411670,"uuid":"1128589171","full_name":"osodevops/docusaurus-llm-docs","owner":"osodevops","description":"📚 GitHub Action to generate LLM-optimized documentation (llms.txt + markdown.zip) from Docusaurus sites. Make your docs accessible to AI assistants.","archived":false,"fork":false,"pushed_at":"2026-01-06T11:13:58.000Z","size":130,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T00:44:00.339Z","etag":null,"topics":["ai","cloudflare","documentation","docusaurus","github-action","llm","markdown","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osodevops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-05T21:39:10.000Z","updated_at":"2026-01-08T06:32:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/osodevops/docusaurus-llm-docs","commit_stats":null,"previous_names":["osodevops/docusaurus-llm-docs"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/osodevops/docusaurus-llm-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osodevops%2Fdocusaurus-llm-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osodevops%2Fdocusaurus-llm-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osodevops%2Fdocusaurus-llm-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osodevops%2Fdocusaurus-llm-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osodevops","download_url":"https://codeload.github.com/osodevops/docusaurus-llm-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osodevops%2Fdocusaurus-llm-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31385942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T01:22:39.193Z","status":"online","status_checked_at":"2026-04-04T02:00:07.569Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cloudflare","documentation","docusaurus","github-action","llm","markdown","typescript"],"created_at":"2026-01-06T08:13:32.352Z","updated_at":"2026-04-04T03:06:15.494Z","avatar_url":"https://github.com/osodevops.png","language":"TypeScript","readme":"# Docusaurus LLM Docs Generator\n\n**A GitHub Action to automatically generate LLM-optimized documentation from Docusaurus sites**\n\nPerfect for teams who want to make their documentation accessible to AI assistants and LLMs. Generates a structured `llms.txt` index and a `markdown.zip` archive following the format popularized by Cloudflare.\n\n\u003cdiv align=\"center\"\u003e\n\n[![GitHub Release](https://img.shields.io/github/v/release/osodevops/docusaurus-llm-docs?label=version)](https://github.com/osodevops/docusaurus-llm-docs/releases)\n[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Docusaurus%20LLM%20Docs-blue?logo=github)](https://github.com/marketplace/actions/docusaurus-llm-docs-generator)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/osodevops/docusaurus-llm-docs?style=social)](https://github.com/osodevops/docusaurus-llm-docs)\n\n\u003c/div\u003e\n\n## Features\n\n- **LLM-Ready Format**: Generates `llms.txt` index for AI navigation\n- **Complete Docs File**: Generates `llms-full.txt` with all documentation in one file\n- **Markdown Archive**: Creates `markdown.zip` with all docs as clean markdown\n- **Automatic Sidebar Injection**: Adds \"LLM Resources\" links to your site's sidebar automatically\n- **Smart Link Transformation**: Converts internal links to absolute URLs\n- **Clean Conversion**: Strips HTML/JSX, preserves code blocks and formatting\n- **Sidebar Aware**: Reads your `sidebars.js` for proper hierarchy\n- **Admonition Support**: Converts Docusaurus admonitions to GitHub alerts\n- **Zero Config**: Works out of the box with any Docusaurus site\n- **Fast**: Processes 50+ pages in under 2 seconds\n\n## Quick Start\n\n### 1. Add the Workflow\n\nCreate `.github/workflows/llm-docs.yml` in your Docusaurus repository:\n\n```yaml\nname: Generate LLM Documentation\n\non:\n  push:\n    branches: [main]\n    paths:\n      - 'docs/**'\n      - 'docusaurus.config.js'\n      - 'sidebars.js'\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\njobs:\n  build-and-deploy:\n    runs-on: ubuntu-latest\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n          cache: 'npm'\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build Docusaurus site\n        run: npm run build\n\n      - name: Generate LLM documentation\n        uses: osodevops/docusaurus-llm-docs@v1\n        id: llm-docs\n        with:\n          build-dir: './build'\n          output-dir: './build/llm-docs'\n          base-url: 'https://yourusername.github.io/your-repo'\n          product-name: 'Your Product Name'\n          tagline: 'Your product tagline'\n\n      - name: Copy LLM docs to build root\n        run: |\n          cp ${{ steps.llm-docs.outputs.llms-txt-path }} ./build/llms.txt\n          cp ${{ steps.llm-docs.outputs.llms-full-txt-path }} ./build/llms-full.txt\n          cp ${{ steps.llm-docs.outputs.markdown-zip-path }} ./build/markdown.zip\n\n      - name: Upload Pages artifact\n        uses: actions/upload-pages-artifact@v3\n        with:\n          path: './build'\n\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4\n```\n\n### 2. Configure Your Settings\n\nUpdate these values in the workflow:\n- `base-url`: Your documentation site URL\n- `product-name`: Your product name (appears in llms.txt header)\n- `tagline`: Short description of your product\n\n### 3. Run the Workflow\n\n**Manual trigger:**\n1. Go to **Actions** tab\n2. Select **Generate LLM Documentation**\n3. Click **Run workflow**\n\n**Automatic runs:**\n- Triggers on push to `main` when docs change\n- Customize triggers in the workflow file\n\n### 4. Access Your LLM Docs\n\nAfter deployment, your LLM documentation is available at:\n- `https://your-site.com/llms.txt` - Lightweight navigation index for LLMs\n- `https://your-site.com/llms-full.txt` - Complete documentation in a single file\n- `https://your-site.com/markdown.zip` - All docs as individual markdown files\n\nThe action also automatically adds an **\"LLM Resources\"** section to your sidebar with links to these files.\n\n## Automatic Sidebar Injection\n\nBy default, the action automatically injects an \"LLM Resources\" section into your Docusaurus sidebar on every page. This makes the LLM documentation easily discoverable by your users.\n\n**Before (your sidebar):**\n```\nGetting Started\nAPI Reference\nGuides\nExamples\n```\n\n**After (automatic injection):**\n```\nGetting Started\nAPI Reference\nGuides\nExamples\nLLM Resources        \u003c-- Automatically added!\n  ├── llms.txt\n  └── markdown.zip\n```\n\n### Disabling Sidebar Injection\n\nIf you prefer to manually configure your sidebar, you can disable automatic injection:\n\n```yaml\n- uses: osodevops/docusaurus-llm-docs@v1\n  with:\n    base-url: 'https://docs.example.com'\n    product-name: 'My Docs'\n    inject-sidebar: 'false'\n```\n\n## Output Example\n\n### llms.txt\n\n```markdown\n# Your Product Documentation\n\nYour product tagline here\n\n\u003e [!TIP]\n\u003e A complete archive of all documentation in Markdown format is available at https://your-site.com/markdown.zip\n\n## Getting Started\n- [Installation](https://your-site.com/getting-started/installation.md): How to install\n- [Quick Start](https://your-site.com/getting-started/quick-start.md): Get running in 5 minutes\n\n## API Reference\n- [Authentication](https://your-site.com/api/authentication.md): API authentication guide\n- [Endpoints](https://your-site.com/api/endpoints.md): Available API endpoints\n```\n\n### llms-full.txt\n\nComplete documentation in a single file, following the Cloudflare format with `\u003cpage\u003e` delimiters:\n\n```markdown\n# Your Product Documentation\n\nYour product tagline here\n\n\u003e This file contains the complete documentation in a single file for LLM consumption.\n\u003e For a lightweight index, see https://your-site.com/llms.txt\n\n\u003cpage\u003e\n---\ntitle: Installation\ndescription: How to install\nsource_url:\n  html: https://your-site.com/getting-started/installation\n  md: https://your-site.com/getting-started/installation.md\n---\n\n# Installation\n\nThis guide covers installing the SDK...\n\n\u003c/page\u003e\n\n\u003cpage\u003e\n---\ntitle: Quick Start\ndescription: Get running in 5 minutes\nsource_url:\n  html: https://your-site.com/getting-started/quick-start\n  md: https://your-site.com/getting-started/quick-start.md\n---\n\n# Quick Start\n\nFollow these steps to get started...\n\n\u003c/page\u003e\n```\n\n### markdown.zip Structure\n\n```\nmarkdown/\n├── getting-started/\n│   ├── installation.md\n│   └── quick-start.md\n├── api/\n│   ├── authentication.md\n│   └── endpoints.md\n└── guides/\n    ├── deployment.md\n    └── troubleshooting.md\n```\n\n### Markdown File Content\n\nClean markdown with proper formatting:\n\n```markdown\n# Installation\n\nThis guide covers installing the SDK in your project.\n\n## Prerequisites\n\n- Node.js 18 or higher\n- npm or yarn\n\n## Install via npm\n\n\\`\\`\\`bash\nnpm install your-package\n\\`\\`\\`\n\n\u003e [!TIP]\n\u003e You can also use yarn: `yarn add your-package`\n```\n\n## Configuration Options\n\n### Action Inputs\n\n| Input | Required | Default | Description |\n|-------|----------|---------|-------------|\n| `build-dir` | No | `./build` | Path to Docusaurus build directory |\n| `output-dir` | No | `./llm-docs` | Output directory for generated files |\n| `base-url` | Yes | - | Base URL for documentation links |\n| `product-name` | Yes | - | Product name for llms.txt header |\n| `tagline` | No | `''` | Product tagline for llms.txt |\n| `sidebar-path` | No | `./sidebars.js` | Path to sidebars.js file |\n| `include-descriptions` | No | `true` | Include page descriptions in llms.txt |\n| `strip-html` | No | `true` | Remove any remaining HTML from output |\n| `inject-sidebar` | No | `true` | Automatically inject LLM Resources into sidebar |\n\n### Action Outputs\n\n| Output | Description |\n|--------|-------------|\n| `llms-txt-path` | Path to generated llms.txt file |\n| `llms-full-txt-path` | Path to generated llms-full.txt file |\n| `markdown-zip-path` | Path to generated markdown.zip archive |\n| `files-generated` | Number of markdown files generated |\n| `sections-count` | Number of documentation sections |\n\n## Advanced Usage\n\n### Without Sidebar\n\nIf your Docusaurus site doesn't use `sidebars.js`, the action automatically discovers pages from the build output:\n\n```yaml\n- uses: osodevops/docusaurus-llm-docs@v1\n  with:\n    base-url: 'https://docs.example.com'\n    product-name: 'My Docs'\n    # sidebar-path not needed - auto-discovery kicks in\n```\n\n### Custom Sidebar Location\n\n```yaml\n- uses: osodevops/docusaurus-llm-docs@v1\n  with:\n    base-url: 'https://docs.example.com'\n    product-name: 'My Docs'\n    sidebar-path: './config/custom-sidebar.js'\n```\n\n### Generate as Artifact Only\n\nDon't deploy to Pages, just create an artifact:\n\n```yaml\n- name: Generate LLM documentation\n  uses: osodevops/docusaurus-llm-docs@v1\n  id: llm-docs\n  with:\n    base-url: 'https://docs.example.com'\n    product-name: 'My Docs'\n    output-dir: './llm-output'\n\n- name: Upload artifact\n  uses: actions/upload-artifact@v4\n  with:\n    name: llm-docs\n    path: ./llm-output/\n```\n\n## Requirements\n\n- Docusaurus 2.x or 3.x site\n- Node.js 20+\n- A built Docusaurus site (`npm run build`)\n- GitHub Actions enabled\n\n## How It Works\n\n1. **Parse Sidebar**: Reads your `sidebars.js` to understand documentation structure\n2. **Find HTML**: Locates all HTML files in the Docusaurus build output\n3. **Convert to Markdown**: Uses Cheerio + Turndown to convert HTML to clean markdown\n4. **Transform Links**: Converts internal links to absolute URLs with `.md` extensions\n5. **Generate Index**: Creates `llms.txt` with hierarchical navigation\n6. **Generate Full Docs**: Creates `llms-full.txt` with all content in one file\n7. **Create Archive**: Packages all markdown files into `markdown.zip`\n8. **Inject Sidebar**: Adds \"LLM Resources\" links to every page's sidebar\n\n## Troubleshooting\n\n### No pages processed\n\n**Check:**\n1. Docusaurus build completed successfully (`npm run build`)\n2. Build directory contains HTML files\n3. `build-dir` path is correct\n\n### Missing pages in output\n\n**Check:**\n1. Pages exist in your `sidebars.js`\n2. Pages have corresponding HTML in build output\n3. Review action logs for warnings about skipped pages\n\n### Links are broken\n\n**Check:**\n1. `base-url` matches your deployed site URL\n2. Include trailing path if using a subdirectory (e.g., `/docs`)\n\n### Sidebar not showing LLM Resources\n\n**Check:**\n1. `inject-sidebar` is not set to `false`\n2. The action runs after the Docusaurus build but before deployment\n3. Review action logs for \"Injected LLM Resources sidebar into X HTML files\"\n\n## Local Development\n\nTest the action locally before deploying:\n\n```bash\n# Clone this repo\ngit clone https://github.com/osodevops/docusaurus-llm-docs.git\ncd docusaurus-llm-docs\n\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run against a Docusaurus build\nBUILD_DIR=/path/to/docusaurus/build \\\nBASE_URL=https://example.com \\\nPRODUCT_NAME=\"My Docs\" \\\nINJECT_SIDEBAR=true \\\nnpm start\n```\n\n## Security \u0026 Privacy\n\n- All processing happens in GitHub Actions\n- No external API calls or data transmission\n- Open source - audit the code yourself\n- Only reads from your build directory\n\n## Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Support\n\n- [Documentation](https://github.com/osodevops/docusaurus-llm-docs#readme)\n- [Report Issues](https://github.com/osodevops/docusaurus-llm-docs/issues)\n- [Discussions](https://github.com/osodevops/docusaurus-llm-docs/discussions)\n\n## Credits\n\nBuilt by [OSO DevOps](https://github.com/osodevops)\n\nInspired by:\n- [Cloudflare's LLM documentation format](https://developers.cloudflare.com/llms.txt)\n- [Zoom Meeting Notes Archiver](https://github.com/marketplace/actions/zoom-to-markdown)\n\nPowered by:\n- [Docusaurus](https://docusaurus.io/)\n- [GitHub Actions](https://github.com/features/actions)\n- [TypeScript](https://www.typescriptlang.org/)\n- [Cheerio](https://cheerio.js.org/)\n- [Turndown](https://github.com/mixmark-io/turndown)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosodevops%2Fdocusaurus-llm-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosodevops%2Fdocusaurus-llm-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosodevops%2Fdocusaurus-llm-docs/lists"}