https://github.com/hopsoft/docfu
The easiest way to turn your existing markdown into a professional website
https://github.com/hopsoft/docfu
docs documentation documentation-gen documentation-tool markdoc markdown markdown-to-html mdx ssg static-site-generator
Last synced: about 2 months ago
JSON representation
The easiest way to turn your existing markdown into a professional website
- Host: GitHub
- URL: https://github.com/hopsoft/docfu
- Owner: hopsoft
- License: mit
- Created: 2025-10-09T21:29:11.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-29T08:06:43.000Z (8 months ago)
- Last Synced: 2026-02-08T06:12:43.756Z (5 months ago)
- Topics: docs, documentation, documentation-gen, documentation-tool, markdoc, markdown, markdown-to-html, mdx, ssg, static-site-generator
- Language: JavaScript
- Homepage:
- Size: 1.01 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📚 Welcome to DocFu
[](https://github.com/hopsoft/docfu/actions/workflows/ci.yml)
**The easiest way to turn your existing markdown into a professional website.**
Just run it on your existing markdown project.
```sh
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](https://en.wikipedia.org/wiki/Command-line_interface) 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._
---
Brought to you by
Advancing Healthcare. Defining Tomorrow.
---
## Prerequisites
- [node](https://nodejs.org/) `>=20`
- [npm](https://www.npmjs.com/) `>=10`
## Table of Contents
- [What's Included?](#whats-included)
- [Components](#components)
- [Content Authoring](#content-authoring)
- [Customization](#customization)
- [Command Line Interface](#command-line-interface)
- [Environment Variables](#environment-variables)
- [Troubleshooting](#troubleshooting)
- [Similar Projects](#similar-projects)
- [Tech Stack](#tech-stack)
- [Contributing](#contributing)
- [License](#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](https://llmstxt.org/)
- **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.
Aside (alerts/callouts)
Highlight important information with callout boxes. Choose from different types to convey the right tone.
[Read the docs](https://starlight.astro.build/components/asides/)
**MDX:**
```markdown
Helpful information for users to know.
```
**Markdoc:**
```markdown
{% aside %}
Helpful information for users to know.
{% /aside %}
```
2.
Badge (inline labels)
Display inline labels for status, versions, or other metadata. Perfect for highlighting new features or changes.
[Read the docs](https://starlight.astro.build/components/badges/)
**MDX:**
```markdown
```
**Markdoc:**
```markdown
{% badge text="New" variant="tip" /%}
```
**Heading Badges:** Use `:badge[text]` syntax for badges in headings
```markdown
## New Feature :badge[Beta]
### API Changes :badge[Breaking]{variant="danger"}
```
3.
Card/CardGrid (highlighted content blocks)
Showcase content in highlighted containers. Use CardGrid to arrange multiple cards in a responsive layout.
[Read the docs](https://starlight.astro.build/components/cards/)
**MDX:**
```markdown
Interesting content you want to highlight.
```
**Markdoc:**
```markdown
{% card title="Check this out" %}
Interesting content you want to highlight.
{% /card %}
```
4.
Code (copyable syntax-highlighted code blocks)
Display code snippets with syntax highlighting and a copy-to-clipboard button.
[Read the docs](https://starlight.astro.build/components/code/)
**MDX:**
```markdown
```
**Markdoc:**
```markdown
{% code code="const hello = 'world';" lang="js" /%}
```
**Standard code fence support**
````markdown
```js
function greet(name) {
return `Hello, ${name}!`
}
```
````
**Mermaid diagram support**
Standard mermaid code blocks work in all formats:
````markdown
```mermaid
graph TD
A[Start] --> B[Process]
B --> C[End]
```
````
You can also use the `Fence` component for explicit control:
**MDX:**
```markdown
B[Process]
B --> C[End]`} lang="mermaid" />
```
**Markdoc:**
```markdown
{% fence code=`graph TD
A[Start] --> B[Process]
B --> C[End]` lang="mermaid" /%}
```
5.
FileTree (file/folder structure)
Visualize directory structures and file hierarchies with an intuitive tree diagram.
[Read the docs](https://starlight.astro.build/components/file-tree/)
**MDX:**
```markdown
- src/
- components/
- Button.jsx
- pages/
- index.astro
```
**Markdoc:**
```markdown
{% filetree %}
- src/
- components/
- Button.jsx
- pages/
- index.astro
{% /filetree %}
```
6.
Icon (built-in icon library)
Add icons from Starlight's built-in icon library to enhance visual communication.
[Read the docs](https://starlight.astro.build/components/icons/)
**Block icons (standalone):**
**MDX:**
```markdown
```
**Markdoc:**
```markdown
{% icon name="star" /%}
```
**Inline icons (within text):**
Use `class="inline"` to display icons inline with text flow.
**MDX:**
```markdown
This is text with an inline icon in the middle.
```
**Markdoc:**
```markdown
This is text with an inline icon {% icon name="star" class="inline" /%} in the middle.
```
7.
LinkButton (call to action)
Create prominent call-to-action buttons that link to other pages or external resources.
[Read the docs](https://starlight.astro.build/components/link-buttons/)
**MDX:**
```markdown
Get Started
```
**Markdoc:**
```markdown
{% linkbutton href="/guides/getting-started/" %}Get Started{% /linkbutton %}
```
8.
LinkCard (clickable cards)
Display links as attractive cards with titles and optional descriptions.
[Read the docs](https://starlight.astro.build/components/link-cards/)
**MDX:**
```markdown
```
**Markdoc:**
```markdown
{% linkcard title="Authoring Markdown" href="/guides/authoring-content/" /%}
```
9.
Steps (step-by-step instructions)
Present sequential instructions with automatic numbering and styled formatting.
[Read the docs](https://starlight.astro.build/components/steps/)
**MDX:**
```markdown
1. First step
2. Second step
3. Third step
```
**Markdoc:**
```markdown
{% steps %}
1. First step
2. Second step
3. Third step
{% /steps %}
```
10.
Tabs/TabItem (tabbed content sections)
Organize related content into tabbed sections, ideal for showing multiple code examples or platform-specific instructions.
[Read the docs](https://starlight.astro.build/components/tabs/)
**MDX:**
```markdown
npm install package
yarn add package
```
**Markdoc:**
```markdown
{% 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`
```astro
---
const {title, type = 'info'} = Astro.props
---
{title}
```
#### Use the Component
**MDX:**
```markdown
Components are automatically imported - just use them!
```
**Markdoc:**
```markdown
{% 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`
```astro
My Custom Documentation
```
_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.
- Assets (images, etc)
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`.
```markdown
```
- Collapsible Sections (styled expandable sections)
Hide optional or detailed content behind expandable sections to keep pages scannable while preserving depth.
```markdown
Click to expand
Additional content goes here.
```
- GitHub Alerts (styled callout boxes)
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).
```markdown
> [!NOTE]
> Helpful information for users to know.
```
- Partials (reusable content)
Share common content like disclaimers, license text, or repeated sections across multiple pages to maintain consistency.
**MDX:**
```markdown
import SharedContent from './path/to/partial.mdx'
```
**Markdoc:**
```markdown
{% 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](docfu.example.yml) for all available options.
> [!TIP]
> Configuration priority:
>
> 1. CLI flags
> 2. `docfu.yml`
> 3. environment variables
> 4. defaults
-
Theme Selection
Choose between professional themes to match your documentation style.
```yaml
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!
-
Custom Styling
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:
```css
/* 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!
-
File Exclusion
Control which files are processed and indexed.
```yaml
# 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
-
Custom Sidebar
Customize navigation structure instead of using auto-generated sidebar.
```yaml
sidebar:
- file: index.md
label: Home
- group: Guides
items:
- quickstart.md
- installation.md
- group: API
directory: api/ # Auto-generate from directory
```
-
Root Directory Configuration
Customize where DocFu creates its build files:
```yaml
# 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)
-
Hierarchical Configuration
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
npx docfu --help
Usage: docfu [options]
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 root directory (default: .docfu)
-y, --yes skip confirmation prompts
prepare [options] Prepare documents for build
Options:
-r, --root root directory (default: .docfu)
-y, --yes skip confirmation prompts
build [options] Build documentation site (default)
Options:
-r, --root root directory (default: .docfu)
-y, --yes skip confirmation prompts
--dry-run verify configuration without building
preview [options] Preview documentation site locally
Options:
-r, --root root directory (default: .docfu)
-y, --yes skip confirmation prompts
-p, --port 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:**
```bash
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: ``
- ✓ From Subdir: ``
- ✗ ``
### 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:**
```bash
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](https://astro.build/) - Full Astro project setup with config and build pipeline
- [Docusaurus](https://docusaurus.io/) - React project, docusaurus.config.js, sidebars.js, specific folder structure
- [Eleventy](https://www.11ty.dev/) - Node project, .eleventy.js config, template directories
- [Hugo](https://gohugo.io/) - Go-based, config.toml, content/ structure, template learning curve
- [Jekyll](https://jekyllrb.com/) - Ruby project, \_config.yml, \_posts/ structure, Gemfile
- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) - MkDocs with theme, requires same setup
- [MkDocs](https://www.mkdocs.org/) - Python, mkdocs.yml config, docs/ folder structure
- [Nextra](https://nextra.site/) - Next.js project, \_meta.js files, pages/ directory structure
- [Slate](https://slatedocs.github.io/slate/) - Ruby/Middleman project, config.rb
- [Sphinx](https://www.sphinx-doc.org/) - Python, conf.py config, reStructuredText format
- [Starlight](https://starlight.astro.build/)\* - Full Astro project, astro.config.mjs, src/content/docs/ structure
- [VitePress](https://vitepress.dev/) - Node project, .vitepress/config.js, src/ directory structure
- [VuePress](https://vuepress.vuejs.org/) - Node project, .vuepress/config.js, specific folder conventions
**Runtime/Browser Rendered (Not Static):**
- [Docsify](https://docsify.js.org/) - Renders markdown in browser at runtime, requires JavaScript enabled, no pre-built HTML
- [Docute](https://docute.egoist.dev/) - Vue-based SPA, fetches and renders markdown on the fly, no build step
**Others:**
See [Awesome Static Generators](https://github.com/myles/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](https://astro.build/) - Static site generator
- [MDX](https://mdxjs.com/) - Markdown with JSX components
- [Markdoc](https://markdoc.dev/) - Structured content with partials
- [Mermaid](https://mermaid.js.org/) - Diagram rendering
- [Pagefind](https://pagefind.app/) - Static search
- [Sharp](https://sharp.pixelplumbing.com/) - Image optimization
- [Shiki](https://shiki.matsu.io/) - Syntax highlighting
- [Starlight GitHub Alerts](https://github.com/HiDeoo/starlight-github-alerts) - GitHub alert syntax support
- [Starlight Heading Badges](https://starlight-heading-badges.vercel.app/) - Heading badge support
- [Starlight LLMs.txt](https://delucis.github.io/starlight-llms-txt/) - AI-friendly documentation generation
- [Starlight](https://starlight.astro.build/) - Documentation theme
## Contributing
Contributions welcome! Fork the repo, make your changes, and open a pull request.
```bash
git clone https://github.com/hopsoft/docfu.git
cd docfu
npm install
npm test
```
Deployment
Publishing new versions to npm requires the following steps.
1. Format and test
```bash
npm run format
npm run test
```
2. Commit changes
3. Update version
```bash
# 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)
```bash
# First: Update version in package.json and commit
git tag -a vX.X.X -m "Release vX.X.X"
```
4. Push changes and tags
```bash
git push [REMOTE] && git push --tags [REMOTE]
```
5. Publish to npm
```bash
npm publish
```
6. Create GitHub release (optional)
Visit the [releases page](https://github.com/hopsoft/docfu/releases) and create a new release from the version tag with release notes.
## License
[MIT](LICENSE)