documaru

Fast Build, Low FCP/LCP Documentation Site Generator | GitHub Action

documaru is a GitHub Action that builds a static documentation site from a plain folder of markdown files. No config file, no build tooling, no dependencies in your repository. Navigation and sidebar are generated from the file tree, page titles come from the first heading.

Usage

Put your pages in a docs folder, add this workflow, and you are done.

name: Deploy documentation

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: denshya/documaru@v1
        with:
          path: docs

      - uses: actions/upload-pages-artifact@v3
        with:
          path: _site

  deploy:
    needs: build
    environment: github-pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/deploy-pages@v4

A copy lives at examples/docs-site.yml.

Inputs

Name	Required	Default	Description
path	no	docs	Folder with the .md/.mdx pages, relative to the repository root.

Outputs

Name	Description
path	Built site folder, relative to the repository root. Always _site.

Docs structure

• index.md is the landing page. It is required.
• 404.md is the not-found page. It is required, the app throws without it.
• Any other .md/.mdx file becomes a page at its folder path. docs/learn/deep.md serves at /learn/deep.
• Page title comes from the first # heading. Navigation labels come from the file name.

GitHub Pages setup

Enable Pages at Settings → Pages → Source: GitHub Actions. Nothing else.

Local development

bun install --frozen-lockfile
bun run build
bun run build:ssg

The static site lands in build/. Serve it with bun run preview.

Known limitations

• Assets are served from /. User pages (user.github.io) work out of the box. Project pages (user.github.io/repo) need a base URL, not supported yet.
• Site brand text is fixed.