{"id":31859402,"url":"https://github.com/hopsoft/docfu","last_synced_at":"2026-05-05T18:39:37.175Z","repository":{"id":318716811,"uuid":"1073270244","full_name":"hopsoft/docfu","owner":"hopsoft","description":"The easiest way to turn your existing markdown into a professional website","archived":false,"fork":false,"pushed_at":"2025-10-29T08:06:43.000Z","size":1064,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T06:12:43.756Z","etag":null,"topics":["docs","documentation","documentation-gen","documentation-tool","markdoc","markdown","markdown-to-html","mdx","ssg","static-site-generator"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/hopsoft.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":"2025-10-09T21:29:11.000Z","updated_at":"2026-02-04T13:03:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"71253e42-88f6-48da-bde6-78c05422210f","html_url":"https://github.com/hopsoft/docfu","commit_stats":null,"previous_names":["hopsoft/docfu"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hopsoft/docfu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hopsoft%2Fdocfu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hopsoft%2Fdocfu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hopsoft%2Fdocfu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hopsoft%2Fdocfu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hopsoft","download_url":"https://codeload.github.com/hopsoft/docfu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hopsoft%2Fdocfu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32663429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["docs","documentation","documentation-gen","documentation-tool","markdoc","markdown","markdown-to-html","mdx","ssg","static-site-generator"],"created_at":"2025-10-12T15:24:04.478Z","updated_at":"2026-05-05T18:39:37.169Z","avatar_url":"https://github.com/hopsoft.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📚 Welcome to DocFu\n\n[![CI](https://github.com/hopsoft/docfu/actions/workflows/ci.yml/badge.svg)](https://github.com/hopsoft/docfu/actions/workflows/ci.yml)\n\n**The easiest way to turn your existing markdown into a professional website.**\n\nJust run it on your existing markdown project.\n\n```sh\nnpx docfu build /path/to/markdown\n```\n\n**That's it!** You now have a beautiful static site ready for deployment.\n\n## Why DocFu?\n\nDocFu is the only static site generator that combines professional documentation features with zero required setup and is entirely [CLI](https://en.wikipedia.org/wiki/Command-line_interface) driven.\n\n- ✓ Works instantly with your existing markdown - no setup required\n- ✓ Multi-format support: Markdown, MDX, and Markdoc work seamlessly together\n- ✓ Zero-config components: Built-in + custom components work everywhere, no imports needed\n- ✓ Themeable: 2 professional themes included (more soon)\n- ✓ Live preview with watch mode for instant feedback\n- ✓ Professional features: Full-text search, dark mode, responsive design\n- ✓ Static output that deploys anywhere\n\n\u003e [!TIP]\n\u003e Docfu works out-of-the-box with sensible defaults and can be easily customized.\n\n## Who's It For?\n\n**Anyone** who wants painless and feature-rich documentation without the overhead of maintaining a JavaScript\nproject and build system for their documentation site.\n\n_e.g. Product Teams, Technical Writers, etc._\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBrought to you by\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.rxvortex.com/\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://ik.imagekit.io/hopsoft/Logos/rxvortex-logo-dark_XFLGrdJ9G.svg?updatedAt=1759900258711\"\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://ik.imagekit.io/hopsoft/Logos/rxvortex-logo-light_UWRG2SGSi.svg?updatedAt=1759900258750\"\u003e\n      \u003cimg alt=\"RxVortex Logo\" src=\"https://ik.imagekit.io/hopsoft/Logos/rxvortex-logo-light_UWRG2SGSi.svg?updatedAt=1759900258750\" width=\"240\" height=\"38.4\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Advancing Healthcare. Defining Tomorrow.\n\u003c/p\u003e\n\n---\n\n## Prerequisites\n\n- [node](https://nodejs.org/) `\u003e=20`\n- [npm](https://www.npmjs.com/) `\u003e=10`\n\n## Table of Contents\n\n\u003c!-- toc --\u003e\n\n- [What's Included?](#whats-included)\n- [Components](#components)\n- [Content Authoring](#content-authoring)\n- [Customization](#customization)\n- [Command Line Interface](#command-line-interface)\n- [Environment Variables](#environment-variables)\n- [Troubleshooting](#troubleshooting)\n- [Similar Projects](#similar-projects)\n- [Tech Stack](#tech-stack)\n- [Contributing](#contributing)\n- [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n## What's Included?\n\n- **Breadcrumbs:** Track your location with automatic breadcrumb trails\n- **Full-Text Search:** Search across all pages instantly\n- **LLM-Friendly:** Generate `/llms.txt` files automatically for [AI supported docs](https://llmstxt.org/)\n- **Light/Dark Mode:** Switch between light and dark themes automatically\n- **MDX:** Use `.mdx` files or MDX syntax in Markdown files\n- **Markdoc:** Use `.mdoc` files or Markdoc syntax in Markdown files\n- **Navigation:** Move between pages with automatic prev/next links\n- **Partials:** Use MDX imports or Markdoc partials to share content across pages\n- **README Support:** Use README.md files as index pages automatically\n- **Responsive Design:** Access on any device with mobile-first responsive design\n- **Sidebar:** Navigate with automatic sidebars built from your file structure\n- **Syntax Highlighting:** Highlight code blocks automatically with VS Code themes\n- **Table of Contents:** Navigate page sections with automatic right-sidebar TOC\n- **Themes:** Choose from 2 professional themes - Nova (modern) or Starlight (classic)\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e Your project can contain a mix of `.md`, `.mdx`, and `.mdoc` files,\n\u003e but each file must use a single syntax: MDX or Markdoc (not both).\n\n## Components\n\n\u003e [!NOTE]\n\u003e\n\u003e - ✓ No setup or imports required\n\u003e - ✓ MDX or Markdoc syntax supported\n\u003e - ✓ Use in any markdown file\n\n### Built-in Components\n\n1. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eAside\u003c/strong\u003e (alerts/callouts)\u003c/summary\u003e\n\n   Highlight important information with callout boxes. Choose from different types to convey the right tone.\n   [Read the docs](https://starlight.astro.build/components/asides/)\n\n   **MDX:**\n\n   ```markdown\n   \u003cAside\u003e\n    Helpful information for users to know.\n   \u003c/Aside\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% aside %}\n   Helpful information for users to know.\n   {% /aside %}\n   ```\n\n   \u003c/details\u003e\n\n2. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eBadge\u003c/strong\u003e (inline labels)\u003c/summary\u003e\n\n   Display inline labels for status, versions, or other metadata. Perfect for highlighting new features or changes.\n   [Read the docs](https://starlight.astro.build/components/badges/)\n\n   **MDX:**\n\n   ```markdown\n   \u003cBadge text=\"New\" variant=\"tip\" /\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% badge text=\"New\" variant=\"tip\" /%}\n   ```\n\n   **Heading Badges:** Use `:badge[text]` syntax for badges in headings\n\n   ```markdown\n   ## New Feature :badge[Beta]\n\n   ### API Changes :badge[Breaking]{variant=\"danger\"}\n   ```\n\n   \u003c/details\u003e\n\n3. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eCard/CardGrid\u003c/strong\u003e (highlighted content blocks)\u003c/summary\u003e\n\n   Showcase content in highlighted containers. Use CardGrid to arrange multiple cards in a responsive layout.\n   [Read the docs](https://starlight.astro.build/components/cards/)\n\n   **MDX:**\n\n   ```markdown\n   \u003cCard title=\"Check this out\"\u003e\n     Interesting content you want to highlight.\n   \u003c/Card\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% card title=\"Check this out\" %}\n   Interesting content you want to highlight.\n   {% /card %}\n   ```\n\n   \u003c/details\u003e\n\n4. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eCode\u003c/strong\u003e (copyable syntax-highlighted code blocks)\u003c/summary\u003e\n\n   Display code snippets with syntax highlighting and a copy-to-clipboard button.\n   [Read the docs](https://starlight.astro.build/components/code/)\n\n   **MDX:**\n\n   ```markdown\n   \u003cCode code=\"const hello = 'world';\" lang=\"js\" /\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% code code=\"const hello = 'world';\" lang=\"js\" /%}\n   ```\n\n   **Standard code fence support**\n\n   ````markdown\n   ```js\n   function greet(name) {\n     return `Hello, ${name}!`\n   }\n   ```\n   ````\n\n   **Mermaid diagram support**\n\n   Standard mermaid code blocks work in all formats:\n\n   ````markdown\n   ```mermaid\n   graph TD\n     A[Start] --\u003e B[Process]\n     B --\u003e C[End]\n   ```\n   ````\n\n   You can also use the `Fence` component for explicit control:\n\n   **MDX:**\n\n   ```markdown\n   \u003cFence code={`graph TD\n     A[Start] --\u003e B[Process]\n     B --\u003e C[End]`} lang=\"mermaid\" /\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% fence code=`graph TD\n     A[Start] --\u003e B[Process]\n     B --\u003e C[End]` lang=\"mermaid\" /%}\n   ```\n\n   \u003c/details\u003e\n\n5. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eFileTree\u003c/strong\u003e (file/folder structure)\u003c/summary\u003e\n\n   Visualize directory structures and file hierarchies with an intuitive tree diagram.\n   [Read the docs](https://starlight.astro.build/components/file-tree/)\n\n   **MDX:**\n\n   ```markdown\n   \u003cFileTree\u003e\n\n   - src/\n     - components/\n       - Button.jsx\n     - pages/\n       - index.astro\n\n   \u003c/FileTree\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% filetree %}\n\n   - src/\n     - components/\n       - Button.jsx\n     - pages/\n       - index.astro\n\n   {% /filetree %}\n   ```\n\n   \u003c/details\u003e\n\n6. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eIcon\u003c/strong\u003e (built-in icon library)\u003c/summary\u003e\n\n   Add icons from Starlight's built-in icon library to enhance visual communication.\n   [Read the docs](https://starlight.astro.build/components/icons/)\n\n   **Block icons (standalone):**\n\n   **MDX:**\n\n   ```markdown\n   \u003cIcon name=\"star\" /\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% icon name=\"star\" /%}\n   ```\n\n   **Inline icons (within text):**\n\n   Use `class=\"inline\"` to display icons inline with text flow.\n\n   **MDX:**\n\n   ```markdown\n   This is text with an inline icon \u003cIcon name=\"star\" class=\"inline\" /\u003e in the middle.\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   This is text with an inline icon {% icon name=\"star\" class=\"inline\" /%} in the middle.\n   ```\n\n   \u003c/details\u003e\n\n7. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eLinkButton\u003c/strong\u003e (call to action)\u003c/summary\u003e\n\n   Create prominent call-to-action buttons that link to other pages or external resources.\n   [Read the docs](https://starlight.astro.build/components/link-buttons/)\n\n   **MDX:**\n\n   ```markdown\n   \u003cLinkButton href=\"/guides/getting-started/\"\u003eGet Started\u003c/LinkButton\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% linkbutton href=\"/guides/getting-started/\" %}Get Started{% /linkbutton %}\n   ```\n\n   \u003c/details\u003e\n\n8. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eLinkCard\u003c/strong\u003e (clickable cards)\u003c/summary\u003e\n\n   Display links as attractive cards with titles and optional descriptions.\n   [Read the docs](https://starlight.astro.build/components/link-cards/)\n\n   **MDX:**\n\n   ```markdown\n   \u003cLinkCard title=\"Authoring Markdown\" href=\"/guides/authoring-content/\" /\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% linkcard title=\"Authoring Markdown\" href=\"/guides/authoring-content/\" /%}\n   ```\n\n   \u003c/details\u003e\n\n9. \u003cdetails\u003e\n   \u003csummary\u003e\u003cstrong\u003eSteps\u003c/strong\u003e (step-by-step instructions)\u003c/summary\u003e\n\n   Present sequential instructions with automatic numbering and styled formatting.\n   [Read the docs](https://starlight.astro.build/components/steps/)\n\n   **MDX:**\n\n   ```markdown\n   \u003cSteps\u003e\n\n   1. First step\n   2. Second step\n   3. Third step\n\n   \u003c/Steps\u003e\n   ```\n\n   **Markdoc:**\n\n   ```markdown\n   {% steps %}\n\n   1. First step\n   2. Second step\n   3. Third step\n\n   {% /steps %}\n   ```\n\n   \u003c/details\u003e\n\n10. \u003cdetails\u003e\n    \u003csummary\u003e\u003cstrong\u003eTabs/TabItem\u003c/strong\u003e (tabbed content sections)\u003c/summary\u003e\n\n    Organize related content into tabbed sections, ideal for showing multiple code examples or platform-specific instructions.\n    [Read the docs](https://starlight.astro.build/components/tabs/)\n\n    **MDX:**\n\n    ```markdown\n    \u003cTabs\u003e\n      \u003cTabItem label=\"npm\"\u003e\n        npm install package\n      \u003c/TabItem\u003e\n      \u003cTabItem label=\"yarn\"\u003e\n        yarn add package\n      \u003c/TabItem\u003e\n    \u003c/Tabs\u003e\n    ```\n\n    **Markdoc:**\n\n    ```markdown\n    {% tabs %}\n    {% tabitem label=\"npm\" %}\n    npm install package\n    {% /tabitem %}\n    {% tabitem label=\"yarn\" %}\n    yarn add package\n    {% /tabitem %}\n    {% /tabs %}\n    ```\n\n    \u003c/details\u003e\n\n### Custom Components\n\nDocFu also supports custom components. Create them as `.astro` files in a `components/` directory:\n\n\u003e [!NOTE]\n\u003e\n\u003e - ✓ Automatically registered, imported, and ready for use\n\u003e - ✓ New attributes automatically supported\n\u003e - ✓ Use in any markdown file\n\u003e - ✓ The default components directory is `components` but can be configured in `docfu.yml`\n\n#### Define the Component\n\n`components/InfoCard.astro`\n\n```astro\n---\nconst {title, type = 'info'} = Astro.props\n---\n\u003cdiv class={`info-card info-card-${type}`}\u003e\n  \u003ch3\u003e{title}\u003c/h3\u003e\n  \u003cslot /\u003e\n\u003c/div\u003e\n```\n\n#### Use the Component\n\n**MDX:**\n\n```markdown\n\u003cInfoCard title=\"Quick Tip\" type=\"success\"\u003e\n  Components are automatically imported - just use them!\n\u003c/InfoCard\u003e\n```\n\n**Markdoc:**\n\n```markdown\n{% infocard title=\"Quick Tip\" type=\"success\" %}\nThis works seamlessly with Markdoc syntax!\n{% /infocard %}\n```\n\n### Component Overrides\n\nReplace Starlight's built-in components with your own by creating components with the same name.\n\n#### Define the Component\n\n`components/Header.astro`\n\n```astro\n\u003cheader class=\"custom-header\"\u003e\n  \u003ch1\u003eMy Custom Documentation\u003c/h1\u003e\n  \u003cnav\u003e\u003c!-- custom navigation --\u003e\u003c/nav\u003e\n\u003c/header\u003e\n```\n\n_See usage examples above._\n\n**That's it!** Your `Header` now overrides the default built-in component. No imports or configuration needed.\n\n## Content Authoring\n\nEnhanced authoring features available everywhere - zero configuration.\n\n- \u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eAssets\u003c/strong\u003e (images, etc)\u003c/summary\u003e\n\n  Use local files and images with relative paths - automatically bundled into the final site.\n\n  \u003e [!NOTE]\n  \u003e The default assets directory is `assets` but can be configured in `docfu.yml`.\n\n  ```markdown\n  ![Logo](assets/images/logo.png)\n  ```\n\n  \u003c/details\u003e\n\n- \u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eCollapsible Sections\u003c/strong\u003e (styled expandable sections)\u003c/summary\u003e\n\n  Hide optional or detailed content behind expandable sections to keep pages scannable while preserving depth.\n\n  ```markdown\n  \u003cdetails\u003e\n    \u003csummary\u003eClick to expand\u003c/summary\u003e\n    Additional content goes here.\n  \u003c/details\u003e\n  ```\n\n  \u003c/details\u003e\n\n- \u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eGitHub Alerts\u003c/strong\u003e (styled callout boxes)\u003c/summary\u003e\n\n  Draw attention to important information with styled callout boxes for notes, warnings, tips, and cautions. Uses familiar [GitHub alert syntax](https://github.com/orgs/community/discussions/16925).\n\n  ```markdown\n  \u003e [!NOTE]\n  \u003e Helpful information for users to know.\n  ```\n\n  \u003c/details\u003e\n\n- \u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003ePartials\u003c/strong\u003e (reusable content)\u003c/summary\u003e\n\n  Share common content like disclaimers, license text, or repeated sections across multiple pages to maintain consistency.\n\n  **MDX:**\n\n  ```markdown\n  import SharedContent from './path/to/partial.mdx'\n\n  \u003cSharedContent /\u003e\n  ```\n\n  **Markdoc:**\n\n  ```markdown\n  {% partial file=\"path/to/partial.md\" /%}\n  ```\n\n  \u003c/details\u003e\n\n## Customization\n\nRun `npx docfu init` or create a `docfu.yml` config file in your markdown project.\nSee [docfu.example.yml](docfu.example.yml) for all available options.\n\n\u003e [!TIP]\n\u003e Configuration priority:\n\u003e\n\u003e 1. CLI flags\n\u003e 2. `docfu.yml`\n\u003e 3. environment variables\n\u003e 4. defaults\n\n- \u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eTheme Selection\u003c/strong\u003e\u003c/summary\u003e\n\n  Choose between professional themes to match your documentation style.\n\n  ```yaml\n  site:\n    name: My Documentation\n    url: https://docs.example.com\n    theme: nova # 'nova' (default, modern) or 'starlight' (classic)\n  ```\n\n  **Available themes:**\n  - **nova** (default) - Modern, polished theme with enhanced visual design\n  - **starlight** - Classic Starlight theme with clean, minimal aesthetic\n\n  More themes coming soon!\n\n  \u003c/details\u003e\n\n- \u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eCustom Styling\u003c/strong\u003e\u003c/summary\u003e\n\n  Customize colors, fonts, layout, and more with CSS files—automatically discovered and loaded.\n\n  **Zero configuration required!** Just place `.css` files in your `assets/` directory and they're automatically loaded.\n\n  Create `assets/styles/custom.css` in your docs:\n\n  ```css\n  /* Override Starlight CSS variables */\n  :root {\n    --sl-color-accent: #ff6b6b;\n    --sl-font: 'Inter', sans-serif;\n  }\n\n  /* Custom element styles */\n  .sl-markdown-content h1 {\n    color: var(--sl-color-accent);\n  }\n  ```\n\n  **Load order:**\n  - CSS files load alphabetically after DocFu's base styles\n  - Your styles take precedence and can override defaults\n  - Use numeric prefixes for explicit ordering: `01-base.css`, `02-theme.css`\n\n  **Example structure:**\n\n  ```\n  docs/\n  └── assets/\n      ├── images/\n      │   └── logo.png\n      └── styles/\n          ├── custom.css\n          └── brand.css\n  ```\n\n  All CSS files under `assets/` are discovered automatically!\n\n  \u003c/details\u003e\n\n- \u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eFile Exclusion\u003c/strong\u003e\u003c/summary\u003e\n\n  Control which files are processed and indexed.\n\n  ```yaml\n  # Completely exclude from processing\n  exclude:\n    - '*.tmp.md'\n    - CONTRIBUTING.md\n    - archive\n\n  # Build but exclude from search\n  unlisted:\n    - drafts\n    - 'internal/**'\n    - 'wip-*.md'\n  ```\n\n  - **exclude**: Files never processed or built\n  - **unlisted**: Files built and accessible, but hidden from search\n\n  \u003c/details\u003e\n\n- \u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eCustom Sidebar\u003c/strong\u003e\u003c/summary\u003e\n\n  Customize navigation structure instead of using auto-generated sidebar.\n\n  ```yaml\n  sidebar:\n    - file: index.md\n      label: Home\n    - group: Guides\n      items:\n        - quickstart.md\n        - installation.md\n    - group: API\n      directory: api/ # Auto-generate from directory\n  ```\n\n  \u003c/details\u003e\n\n- \u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eRoot Directory Configuration\u003c/strong\u003e\u003c/summary\u003e\n\n  Customize where DocFu creates its build files:\n\n  ```yaml\n  # Change default .docfu directory location\n  root: /tmp/docfu-build\n  # or relative path\n  root: ../builds/.docfu\n  ```\n\n  **Configuration priority:** CLI `--root` flag \u003e `docfu.yml` `root:` \u003e `DOCFU_ROOT` env var \u003e `.docfu` (default)\n\n  \u003c/details\u003e\n\n- \u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eHierarchical Configuration\u003c/strong\u003e\u003c/summary\u003e\n\n  Place `docfu.yml` files in subdirectories for granular control.\n\n  ```\n  docs/\n  ├── docfu.yml           # Root config (site info, root directory)\n  ├── guides/\n  │   └── docfu.yml       # Guides-specific config (frontmatter defaults)\n  └── api/\n      └── docfu.yml       # API-specific config (exclude patterns, frontmatter)\n  ```\n\n  Configs cascade naturally - subdirectory configs override parent configs for their scope.\n\n  \u003c/details\u003e\n\n## Command Line Interface\n\n### Configure Your Project\n\n```bash\nnpx docfu init /path/to/markdown\n```\n\n- **What it does:** Creates a `docfu.yml` configuration file in your markdown project\n- **When to use:** Whenever you want to customize\n\n### Prepare Documents\n\n```bash\nnpx docfu prepare /path/to/markdown\n```\n\n- **What it does:** Processes and transforms your markdown files (no build step)\n- **When to use:** Debugging transformations, inspecting processed files, or preparing for manual builds\n\n### Build Your Site\n\n```bash\nnpx docfu build /path/to/markdown\n```\n\n- **What it does:** Prepares documents and builds a complete static website\n- **When to use:** Building for deployment or testing final output\n\n### Preview Your Site\n\n```bash\nnpx docfu preview /path/to/markdown\n```\n\n- **What it does:** Builds your website and hosts it locally\n- **When to use:** Local testing before deployment\n\n### Command Reference\n\n```bash\nnpx docfu --help\n\nUsage: docfu [options] \u003csource\u003e\n\nGenerate production-ready documentation websites from markdown\n\nOptions:\n  -h, --help                  display help for command\n  -v, --version               output version number\n\nCommands:\n  init [options] [source]     Initialize DocFu configuration\n    Options:\n      -r, --root \u003cpath\u003e       root directory (default: .docfu)\n      -y, --yes               skip confirmation prompts\n\n  prepare [options] \u003csource\u003e  Prepare documents for build\n    Options:\n      -r, --root \u003cpath\u003e       root directory (default: .docfu)\n      -y, --yes               skip confirmation prompts\n\n  build [options] \u003csource\u003e    Build documentation site (default)\n    Options:\n      -r, --root \u003cpath\u003e       root directory (default: .docfu)\n      -y, --yes               skip confirmation prompts\n      --dry-run               verify configuration without building\n\n  preview [options] \u003csource\u003e  Preview documentation site locally\n    Options:\n      -r, --root \u003cpath\u003e       root directory (default: .docfu)\n      -y, --yes               skip confirmation prompts\n      -p, --port \u003cnumber\u003e     preview server port (default: 4321)\n      --watch                 watch for changes and rebuild\n\n  help [command]              display help for command\n\nExamples:\n  $ docfu ./docs\n  $ docfu prepare ./docs\n  $ docfu preview ./my-docs --port 3000\n  $ docfu build ./docs --root /tmp/my-docs\n  $ docfu build ./docs --dry-run\n\nEnvironment Variables:\n  DOCFU_SOURCE   Source markdown directory\n  DOCFU_ROOT     Root directory (default: .docfu)\n```\n\n## Environment Variables\n\nOverride default paths using environment variables:\n\n- **DOCFU_SOURCE** - Source markdown directory\n- **DOCFU_ROOT** - Root directory for workspace and build output (default: `.docfu`)\n\n**Configuration priority:** CLI flags \u003e `docfu.yml` \u003e environment variables \u003e defaults\n\n**Example:**\n\n```bash\nDOCFU_ROOT=/tmp/docfu-build npx docfu build ./docs\n```\n\n## Troubleshooting\n\n### Links Not Working\n\nUse relative paths in markdown links.\n\n- ✓ `[Guide](./guides/intro.md)`\n- ✗ `[Guide](/guides/intro.md)`\n\n### Images Not Displaying\n\nPlace images in `assets/` directory and use relative paths.\n\n- ✓ From Root: `![Logo](assets/images/logo.png)`\n- ✓ From Subdir: `![Logo](../assets/images/logo.png)`\n- ✗ `![Logo](/assets/images/logo.png)`\n\n### Inspect Pre-Processed Markdown\n\nThe workspace contains your prepared (pre-processed) markdown files with all transformations applied before building.\nInspecting these files helps diagnose issues with syntax detection, component imports, or file conversions.\n\n**Directory structure:**\n\n```\n.docfu/                    # Root (created in current working directory)\n├── workspace/             # Processed markdown + Astro project\n│   ├── src/\n│   │   ├── components/    # Processed components (.astro)\n│   │   └── content/docs/  # Processed markdown files\n│   ├── public/            # Bundled assets (images, CSS, etc.)\n│   ├── astro.config.mjs   # Generated Astro configuration\n│   └── package.json       # Astro project manifest\n├── dist/                  # Built static site (ready for deployment)\n├── config.yml             # Merged DocFu configuration\n└── manifest.json          # Build manifest (components, docs, CSS)\n```\n\n**What you'll find in the workspace:**\n\n- File conversions (based on content/syntax detection):\n  - `README.md` → `index.md` (when no `index.md` exists)\n  - `.md` → `.mdx` (when JSX components detected)\n  - `.md` → `.mdoc` (when Markdoc syntax detected)\n- Component processing:\n  - Components copied from source `components/` to workspace `src/components/`\n  - All components finalized as `.astro` files\n- Auto-enhanced frontmatter (titles, metadata)\n- Auto-generated component imports for MDX files\n- Updated partial references for Markdoc files\n- Bundled assets with preserved directory structure\n\n**How to inspect:**\n\n```bash\nnpx docfu prepare /path/to/markdown\nls -la .docfu/workspace/src/content/docs/  # Processed markdown\nls -la .docfu/workspace/src/components/    # Processed components\ncat .docfu/manifest.json                   # Build metadata\n```\n\n_Note: `.docfu` is created in the current working directory where `npx docfu` is executed._\n_The root directory can be customized via `--root` flag, `docfu.yml`, or `DOCFU_ROOT` env var._\n\n**Common troubleshooting scenarios:**\n\n- **Components not rendering?** Check if MDX files have the expected imports in workspace\n- **Wrong file extension?** Verify `.md` files were converted to `.mdx` or `.mdoc` correctly\n- **Component not found?** Verify component exists in `workspace/src/components/` with `.astro` extension\n- **Partials not working?** Inspect partial file references and paths in the workspace\n- **Frontmatter issues?** Review processed frontmatter in workspace files\n- **Assets missing?** Check if files are in `workspace/public/` with correct directory structure\n\n## Similar Projects\n\n### Documentation-Specific Generators\n\n**Requires Project Setup / Restructuring:**\n\nThese tools require creating a project with config files, specific folder structures, or restructuring your existing markdown:\n\n- [Astro](https://astro.build/) - Full Astro project setup with config and build pipeline\n- [Docusaurus](https://docusaurus.io/) - React project, docusaurus.config.js, sidebars.js, specific folder structure\n- [Eleventy](https://www.11ty.dev/) - Node project, .eleventy.js config, template directories\n- [Hugo](https://gohugo.io/) - Go-based, config.toml, content/ structure, template learning curve\n- [Jekyll](https://jekyllrb.com/) - Ruby project, \\_config.yml, \\_posts/ structure, Gemfile\n- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) - MkDocs with theme, requires same setup\n- [MkDocs](https://www.mkdocs.org/) - Python, mkdocs.yml config, docs/ folder structure\n- [Nextra](https://nextra.site/) - Next.js project, \\_meta.js files, pages/ directory structure\n- [Slate](https://slatedocs.github.io/slate/) - Ruby/Middleman project, config.rb\n- [Sphinx](https://www.sphinx-doc.org/) - Python, conf.py config, reStructuredText format\n- [Starlight](https://starlight.astro.build/)\\* - Full Astro project, astro.config.mjs, src/content/docs/ structure\n- [VitePress](https://vitepress.dev/) - Node project, .vitepress/config.js, src/ directory structure\n- [VuePress](https://vuepress.vuejs.org/) - Node project, .vuepress/config.js, specific folder conventions\n\n**Runtime/Browser Rendered (Not Static):**\n\n- [Docsify](https://docsify.js.org/) - Renders markdown in browser at runtime, requires JavaScript enabled, no pre-built HTML\n- [Docute](https://docute.egoist.dev/) - Vue-based SPA, fetches and renders markdown on the fly, no build step\n\n**Others:**\n\nSee [Awesome Static Generators](https://github.com/myles/awesome-static-generators) for hundreds more (all require project setup).\n\n### Why Choose DocFu?\n\nMost tools force you to choose: simple setup OR rich features. DocFu gives you both.\n\n1. **CLI-driven simplicity** - No setup or complex project to manage\n2. **Works with existing repos** - No restructuring, config files, or source modifications required\n3. **Multi-format support** - MD, MDX, and Markdoc work seamlessly together\n4. **Zero-config components** - Built-in + custom components work everywhere, no imports needed\n5. **Live preview with watch mode** - Instant feedback while writing\n6. **Professional features** - Full Starlight component library, search, themes, dark mode, responsive design\n7. **Isolated workspace** - Source stays pristine, builds with separate `.docfu/` directory\n8. **True static output** - Deploy anywhere (vs runtime rendering like Docsify)\n\n**Why DocFu over Starlight?** Starlight requires creating an Astro project with package.json, node_modules, and config files in your documentation repository. DocFu gives you all of Starlight's features without polluting your docs project: just point it at your existing markdown and build.\n\n## Tech Stack\n\n- [Astro](https://astro.build/) - Static site generator\n- [MDX](https://mdxjs.com/) - Markdown with JSX components\n- [Markdoc](https://markdoc.dev/) - Structured content with partials\n- [Mermaid](https://mermaid.js.org/) - Diagram rendering\n- [Pagefind](https://pagefind.app/) - Static search\n- [Sharp](https://sharp.pixelplumbing.com/) - Image optimization\n- [Shiki](https://shiki.matsu.io/) - Syntax highlighting\n- [Starlight GitHub Alerts](https://github.com/HiDeoo/starlight-github-alerts) - GitHub alert syntax support\n- [Starlight Heading Badges](https://starlight-heading-badges.vercel.app/) - Heading badge support\n- [Starlight LLMs.txt](https://delucis.github.io/starlight-llms-txt/) - AI-friendly documentation generation\n- [Starlight](https://starlight.astro.build/) - Documentation theme\n\n## Contributing\n\nContributions welcome! Fork the repo, make your changes, and open a pull request.\n\n```bash\ngit clone https://github.com/hopsoft/docfu.git\ncd docfu\nnpm install\nnpm test\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eDeployment\u003c/summary\u003e\n\nPublishing new versions to npm requires the following steps.\n\n1. Format and test\n\n   ```bash\n   npm run format\n   npm run test\n   ```\n\n2. Commit changes\n\n3. Update version\n\n   ```bash\n   # For bug fixes\n   npm version patch\n\n   # For new features (backward compatible)\n   npm version minor\n\n   # For breaking changes\n   npm version major\n   ```\n\n   _This updates `package.json` and creates a git tag automatically._\n\n   Alt (manual tag)\n\n   ```bash\n   # First: Update version in package.json and commit\n   git tag -a vX.X.X -m \"Release vX.X.X\"\n   ```\n\n4. Push changes and tags\n\n   ```bash\n   git push [REMOTE] \u0026\u0026 git push --tags [REMOTE]\n   ```\n\n5. Publish to npm\n\n   ```bash\n   npm publish\n   ```\n\n6. Create GitHub release (optional)\n\n   Visit the [releases page](https://github.com/hopsoft/docfu/releases) and create a new release from the version tag with release notes.\n\n\u003c/details\u003e\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhopsoft%2Fdocfu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhopsoft%2Fdocfu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhopsoft%2Fdocfu/lists"}