📚 Welcome to DocFu

The easiest way to turn your existing markdown into a professional website.

Just run it on your existing markdown project.

npx docfu build /path/to/markdown

That's it! You now have a beautiful static site ready for deployment.

Why DocFu?

DocFu is the only static site generator that combines professional documentation features with zero required setup and is entirely CLI driven.

• ✓ Works instantly with your existing markdown - no setup required
• ✓ Multi-format support: Markdown, MDX, and Markdoc work seamlessly together
• ✓ Zero-config components: Built-in + custom components work everywhere, no imports needed
• ✓ Themeable: 2 professional themes included (more soon)
• ✓ Live preview with watch mode for instant feedback
• ✓ Professional features: Full-text search, dark mode, responsive design
• ✓ Static output that deploys anywhere

[!TIP] Docfu works out-of-the-box with sensible defaults and can be easily customized.

Who's It For?

Anyone who wants painless and feature-rich documentation without the overhead of maintaining a JavaScript project and build system for their documentation site.

e.g. Product Teams, Technical Writers, etc.

Prerequisites

• node >=20
• npm >=10

Table of Contents

• What's Included?
• Components
• Content Authoring
• Customization
• Command Line Interface
• Environment Variables
• Troubleshooting
• Similar Projects
• Tech Stack
• Contributing
• License

What's Included?

• Breadcrumbs: Track your location with automatic breadcrumb trails
• Full-Text Search: Search across all pages instantly
• LLM-Friendly: Generate /llms.txt files automatically for AI supported docs
• Light/Dark Mode: Switch between light and dark themes automatically
• MDX: Use .mdx files or MDX syntax in Markdown files
• Markdoc: Use .mdoc files or Markdoc syntax in Markdown files
• Navigation: Move between pages with automatic prev/next links
• Partials: Use MDX imports or Markdoc partials to share content across pages
• README Support: Use README.md files as index pages automatically
• Responsive Design: Access on any device with mobile-first responsive design
• Sidebar: Navigate with automatic sidebars built from your file structure
• Syntax Highlighting: Highlight code blocks automatically with VS Code themes
• Table of Contents: Navigate page sections with automatic right-sidebar TOC
• Themes: Choose from 2 professional themes - Nova (modern) or Starlight (classic)

[!IMPORTANT]

Your project can contain a mix of .md, .mdx, and .mdoc files, but each file must use a single syntax: MDX or Markdoc (not both).

Components

[!NOTE]

• ✓ No setup or imports required
• ✓ MDX or Markdoc syntax supported
• ✓ Use in any markdown file

Built-in Components

1. Highlight important information with callout boxes. Choose from different types to convey the right tone. Read the docs

   MDX:

   <Aside>
    Helpful information for users to know.
   </Aside>

   Markdoc:

   {% aside %}
   Helpful information for users to know.
   {% /aside %}

2. Display inline labels for status, versions, or other metadata. Perfect for highlighting new features or changes. Read the docs

   MDX:

   <Badge text="New" variant="tip" />

   Markdoc:

   {% badge text="New" variant="tip" /%}

   Heading Badges: Use :badge[text] syntax for badges in headings

   ## New Feature :badge[Beta]
   
   ### API Changes :badge[Breaking]{variant="danger"}

3. Showcase content in highlighted containers. Use CardGrid to arrange multiple cards in a responsive layout. Read the docs

   MDX:

   <Card title="Check this out">
     Interesting content you want to highlight.
   </Card>

   Markdoc:

   {% card title="Check this out" %}
   Interesting content you want to highlight.
   {% /card %}

4. Display code snippets with syntax highlighting and a copy-to-clipboard button. Read the docs

   MDX:

   <Code code="const hello = 'world';" lang="js" />

   Markdoc:

   {% code code="const hello = 'world';" lang="js" /%}

   Standard code fence support

   ```js
   function greet(name) {
     return `Hello, ${name}!`
   }
   ```

   Mermaid diagram support

   Standard mermaid code blocks work in all formats:

   ```mermaid
   graph TD
     A[Start] --> B[Process]
     B --> C[End]
   ```

   You can also use the Fence component for explicit control:

   MDX:

   <Fence code={`graph TD
     A[Start] --> B[Process]
     B --> C[End]`} lang="mermaid" />

   Markdoc:

   {% fence code=`graph TD
     A[Start] --> B[Process]
     B --> C[End]` lang="mermaid" /%}

5. Visualize directory structures and file hierarchies with an intuitive tree diagram. Read the docs

   MDX:

   <FileTree>
   
   - src/
     - components/
       - Button.jsx
     - pages/
       - index.astro
   
   </FileTree>

   Markdoc:

   {% filetree %}
   
   - src/
     - components/
       - Button.jsx
     - pages/
       - index.astro
   
   {% /filetree %}

6. Add icons from Starlight's built-in icon library to enhance visual communication. Read the docs

   Block icons (standalone):

   MDX:

   <Icon name="star" />

   Markdoc:

   {% icon name="star" /%}

   Inline icons (within text):

   Use class="inline" to display icons inline with text flow.

   MDX:

   This is text with an inline icon <Icon name="star" class="inline" /> in the middle.

   Markdoc:

   This is text with an inline icon {% icon name="star" class="inline" /%} in the middle.

7. Create prominent call-to-action buttons that link to other pages or external resources. Read the docs

   MDX:

   <LinkButton href="/guides/getting-started/">Get Started</LinkButton>

   Markdoc:

   {% linkbutton href="/guides/getting-started/" %}Get Started{% /linkbutton %}

8. Display links as attractive cards with titles and optional descriptions. Read the docs

   MDX:

   <LinkCard title="Authoring Markdown" href="/guides/authoring-content/" />

   Markdoc:

   {% linkcard title="Authoring Markdown" href="/guides/authoring-content/" /%}

9. Present sequential instructions with automatic numbering and styled formatting. Read the docs

   MDX:

   <Steps>
   
   1. First step
   2. Second step
   3. Third step
   
   </Steps>

   Markdoc:

   {% steps %}
   
   1. First step
   2. Second step
   3. Third step
   
   {% /steps %}

10. Organize related content into tabbed sections, ideal for showing multiple code examples or platform-specific instructions. Read the docs

    MDX:

    <Tabs>
      <TabItem label="npm">
        npm install package
      </TabItem>
      <TabItem label="yarn">
        yarn add package
      </TabItem>
    </Tabs>

    Markdoc:

    {% tabs %}
    {% tabitem label="npm" %}
    npm install package
    {% /tabitem %}
    {% tabitem label="yarn" %}
    yarn add package
    {% /tabitem %}
    {% /tabs %}

Custom Components

DocFu also supports custom components. Create them as .astro files in a components/ directory:

[!NOTE]

• ✓ Automatically registered, imported, and ready for use
• ✓ New attributes automatically supported
• ✓ Use in any markdown file
• ✓ The default components directory is components but can be configured in docfu.yml

Define the Component

components/InfoCard.astro

---
const {title, type = 'info'} = Astro.props
---
<div class={`info-card info-card-${type}`}>
  <h3>{title}</h3>
  <slot />
</div>

Use the Component

MDX:

<InfoCard title="Quick Tip" type="success">
  Components are automatically imported - just use them!
</InfoCard>

Markdoc:

{% infocard title="Quick Tip" type="success" %}
This works seamlessly with Markdoc syntax!
{% /infocard %}

Component Overrides

Replace Starlight's built-in components with your own by creating components with the same name.

Define the Component

components/Header.astro

<header class="custom-header">
  <h1>My Custom Documentation</h1>
  <nav><!-- custom navigation --></nav>
</header>

See usage examples above.

That's it! Your Header now overrides the default built-in component. No imports or configuration needed.

Content Authoring

Enhanced authoring features available everywhere - zero configuration.

• Use local files and images with relative paths - automatically bundled into the final site.

  [!NOTE] The default assets directory is assets but can be configured in docfu.yml.

  ![Logo](assets/images/logo.png)

• Hide optional or detailed content behind expandable sections to keep pages scannable while preserving depth.

  <details>
    <summary>Click to expand</summary>
    Additional content goes here.
  </details>

• Draw attention to important information with styled callout boxes for notes, warnings, tips, and cautions. Uses familiar GitHub alert syntax.

  > [!NOTE]
  > Helpful information for users to know.

• Share common content like disclaimers, license text, or repeated sections across multiple pages to maintain consistency.

  MDX:

  import SharedContent from './path/to/partial.mdx'
  
  <SharedContent />

  Markdoc:

  {% partial file="path/to/partial.md" /%}

Customization

Run npx docfu init or create a docfu.yml config file in your markdown project. See docfu.example.yml for all available options.

[!TIP] Configuration priority:

1. CLI flags
2. docfu.yml
3. environment variables
4. defaults

• Choose between professional themes to match your documentation style.

  site:
    name: My Documentation
    url: https://docs.example.com
    theme: nova # 'nova' (default, modern) or 'starlight' (classic)

  Available themes:

  • nova (default) - Modern, polished theme with enhanced visual design
  • starlight - Classic Starlight theme with clean, minimal aesthetic

  More themes coming soon!

• Customize colors, fonts, layout, and more with CSS files—automatically discovered and loaded.

  Zero configuration required! Just place .css files in your assets/ directory and they're automatically loaded.

  Create assets/styles/custom.css in your docs:

  /* Override Starlight CSS variables */
  :root {
    --sl-color-accent: #ff6b6b;
    --sl-font: 'Inter', sans-serif;
  }
  
  /* Custom element styles */
  .sl-markdown-content h1 {
    color: var(--sl-color-accent);
  }

  Load order:

  • CSS files load alphabetically after DocFu's base styles
  • Your styles take precedence and can override defaults
  • Use numeric prefixes for explicit ordering: 01-base.css, 02-theme.css

  Example structure:

  docs/
  └── assets/
      ├── images/
      │   └── logo.png
      └── styles/
          ├── custom.css
          └── brand.css

  All CSS files under assets/ are discovered automatically!

• Control which files are processed and indexed.

  # Completely exclude from processing
  exclude:
    - '*.tmp.md'
    - CONTRIBUTING.md
    - archive
  
  # Build but exclude from search
  unlisted:
    - drafts
    - 'internal/**'
    - 'wip-*.md'

  • exclude: Files never processed or built
  • unlisted: Files built and accessible, but hidden from search

• Customize navigation structure instead of using auto-generated sidebar.

  sidebar:
    - file: index.md
      label: Home
    - group: Guides
      items:
        - quickstart.md
        - installation.md
    - group: API
      directory: api/ # Auto-generate from directory

• Customize where DocFu creates its build files:

  # Change default .docfu directory location
  root: /tmp/docfu-build
  # or relative path
  root: ../builds/.docfu

  Configuration priority: CLI --root flag > docfu.yml root: > DOCFU_ROOT env var > .docfu (default)

• Place docfu.yml files in subdirectories for granular control.

  docs/
  ├── docfu.yml           # Root config (site info, root directory)
  ├── guides/
  │   └── docfu.yml       # Guides-specific config (frontmatter defaults)
  └── api/
      └── docfu.yml       # API-specific config (exclude patterns, frontmatter)

  Configs cascade naturally - subdirectory configs override parent configs for their scope.

Command Line Interface

Configure Your Project

npx docfu init /path/to/markdown

• What it does: Creates a docfu.yml configuration file in your markdown project
• When to use: Whenever you want to customize

Prepare Documents

npx docfu prepare /path/to/markdown

• What it does: Processes and transforms your markdown files (no build step)
• When to use: Debugging transformations, inspecting processed files, or preparing for manual builds

Build Your Site

npx docfu build /path/to/markdown

• What it does: Prepares documents and builds a complete static website
• When to use: Building for deployment or testing final output

Preview Your Site

npx docfu preview /path/to/markdown

• What it does: Builds your website and hosts it locally
• When to use: Local testing before deployment

Command Reference

npx docfu --help

Usage: docfu [options] <source>

Generate production-ready documentation websites from markdown

Options:
  -h, --help                  display help for command
  -v, --version               output version number

Commands:
  init [options] [source]     Initialize DocFu configuration
    Options:
      -r, --root <path>       root directory (default: .docfu)
      -y, --yes               skip confirmation prompts

  prepare [options] <source>  Prepare documents for build
    Options:
      -r, --root <path>       root directory (default: .docfu)
      -y, --yes               skip confirmation prompts

  build [options] <source>    Build documentation site (default)
    Options:
      -r, --root <path>       root directory (default: .docfu)
      -y, --yes               skip confirmation prompts
      --dry-run               verify configuration without building

  preview [options] <source>  Preview documentation site locally
    Options:
      -r, --root <path>       root directory (default: .docfu)
      -y, --yes               skip confirmation prompts
      -p, --port <number>     preview server port (default: 4321)
      --watch                 watch for changes and rebuild

  help [command]              display help for command

Examples:
  $ docfu ./docs
  $ docfu prepare ./docs
  $ docfu preview ./my-docs --port 3000
  $ docfu build ./docs --root /tmp/my-docs
  $ docfu build ./docs --dry-run

Environment Variables:
  DOCFU_SOURCE   Source markdown directory
  DOCFU_ROOT     Root directory (default: .docfu)

Environment Variables

Override default paths using environment variables:

• DOCFU_SOURCE - Source markdown directory
• DOCFU_ROOT - Root directory for workspace and build output (default: .docfu)

Configuration priority: CLI flags > docfu.yml > environment variables > defaults

Example:

DOCFU_ROOT=/tmp/docfu-build npx docfu build ./docs

Troubleshooting

Links Not Working

Use relative paths in markdown links.

• ✓ [Guide](./guides/intro.md)
• ✗ [Guide](/guides/intro.md)

Images Not Displaying

Place images in assets/ directory and use relative paths.

• ✓ From Root: ![Logo](assets/images/logo.png)
• ✓ From Subdir: ![Logo](../assets/images/logo.png)
• ✗ ![Logo](/assets/images/logo.png)

Inspect Pre-Processed Markdown

The workspace contains your prepared (pre-processed) markdown files with all transformations applied before building. Inspecting these files helps diagnose issues with syntax detection, component imports, or file conversions.

Directory structure:

.docfu/                    # Root (created in current working directory)
├── workspace/             # Processed markdown + Astro project
│   ├── src/
│   │   ├── components/    # Processed components (.astro)
│   │   └── content/docs/  # Processed markdown files
│   ├── public/            # Bundled assets (images, CSS, etc.)
│   ├── astro.config.mjs   # Generated Astro configuration
│   └── package.json       # Astro project manifest
├── dist/                  # Built static site (ready for deployment)
├── config.yml             # Merged DocFu configuration
└── manifest.json          # Build manifest (components, docs, CSS)

What you'll find in the workspace:

• File conversions (based on content/syntax detection):
  • README.md → index.md (when no index.md exists)
  • .md → .mdx (when JSX components detected)
  • .md → .mdoc (when Markdoc syntax detected)
• Component processing:
  • Components copied from source components/ to workspace src/components/
  • All components finalized as .astro files
• Auto-enhanced frontmatter (titles, metadata)
• Auto-generated component imports for MDX files
• Updated partial references for Markdoc files
• Bundled assets with preserved directory structure

How to inspect:

npx docfu prepare /path/to/markdown
ls -la .docfu/workspace/src/content/docs/  # Processed markdown
ls -la .docfu/workspace/src/components/    # Processed components
cat .docfu/manifest.json                   # Build metadata

Note: .docfu is created in the current working directory where npx docfu is executed. The root directory can be customized via --root flag, docfu.yml, or DOCFU_ROOT env var.

Common troubleshooting scenarios:

• Components not rendering? Check if MDX files have the expected imports in workspace
• Wrong file extension? Verify .md files were converted to .mdx or .mdoc correctly
• Component not found? Verify component exists in workspace/src/components/ with .astro extension
• Partials not working? Inspect partial file references and paths in the workspace
• Frontmatter issues? Review processed frontmatter in workspace files
• Assets missing? Check if files are in workspace/public/ with correct directory structure

Similar Projects

Documentation-Specific Generators

Requires Project Setup / Restructuring:

These tools require creating a project with config files, specific folder structures, or restructuring your existing markdown:

• Astro - Full Astro project setup with config and build pipeline
• Docusaurus - React project, docusaurus.config.js, sidebars.js, specific folder structure
• Eleventy - Node project, .eleventy.js config, template directories
• Hugo - Go-based, config.toml, content/ structure, template learning curve
• Jekyll - Ruby project, _config.yml, _posts/ structure, Gemfile
• MkDocs Material - MkDocs with theme, requires same setup
• MkDocs - Python, mkdocs.yml config, docs/ folder structure
• Nextra - Next.js project, _meta.js files, pages/ directory structure
• Slate - Ruby/Middleman project, config.rb
• Sphinx - Python, conf.py config, reStructuredText format
• Starlight* - Full Astro project, astro.config.mjs, src/content/docs/ structure
• VitePress - Node project, .vitepress/config.js, src/ directory structure
• VuePress - Node project, .vuepress/config.js, specific folder conventions

Runtime/Browser Rendered (Not Static):

• Docsify - Renders markdown in browser at runtime, requires JavaScript enabled, no pre-built HTML
• Docute - Vue-based SPA, fetches and renders markdown on the fly, no build step

Others:

See Awesome Static Generators for hundreds more (all require project setup).

Why Choose DocFu?

Most tools force you to choose: simple setup OR rich features. DocFu gives you both.

1. CLI-driven simplicity - No setup or complex project to manage
2. Works with existing repos - No restructuring, config files, or source modifications required
3. Multi-format support - MD, MDX, and Markdoc work seamlessly together
4. Zero-config components - Built-in + custom components work everywhere, no imports needed
5. Live preview with watch mode - Instant feedback while writing
6. Professional features - Full Starlight component library, search, themes, dark mode, responsive design
7. Isolated workspace - Source stays pristine, builds with separate .docfu/ directory
8. True static output - Deploy anywhere (vs runtime rendering like Docsify)

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.

Tech Stack

• Astro - Static site generator
• MDX - Markdown with JSX components
• Markdoc - Structured content with partials
• Mermaid - Diagram rendering
• Pagefind - Static search
• Sharp - Image optimization
• Shiki - Syntax highlighting
• Starlight GitHub Alerts - GitHub alert syntax support
• Starlight Heading Badges - Heading badge support
• Starlight LLMs.txt - AI-friendly documentation generation
• Starlight - Documentation theme

Contributing

Contributions welcome! Fork the repo, make your changes, and open a pull request.

git clone https://github.com/hopsoft/docfu.git
cd docfu
npm install
npm test

Publishing new versions to npm requires the following steps.

1. Format and test

   npm run format
   npm run test

2. Commit changes

3. Update version

   # For bug fixes
   npm version patch
   
   # For new features (backward compatible)
   npm version minor
   
   # For breaking changes
   npm version major

   This updates package.json and creates a git tag automatically.

   Alt (manual tag)

   # First: Update version in package.json and commit
   git tag -a vX.X.X -m "Release vX.X.X"

4. Push changes and tags

   git push [REMOTE] && git push --tags [REMOTE]

5. Publish to npm

   npm publish

6. Create GitHub release (optional)

   Visit the releases page and create a new release from the version tag with release notes.

License

MIT