hellodocs

Embedded project documentation.

A single, no-dependencies, cross-platform AWK script that converts Markdown to raw HTML documentation. Drop the output into your project, Docker image, or repo.

┌───────────┐                          ┌────────────┐                  ┌─────┬─────────┐
│ README.md │                          │ /docs      │                  │ nav │ hello   │
│ ───────── │                          │ index.html │                  │ ... │─d─o─c─s─│
│ # Usage   │ ──▶  $ awk hellodocs ──▶ │ 1.html     │ ──▶ browser ──▶  │ ... │ ·· ···· │
│ # API     │                          │ 2.html     │                  │ ··· │ ·· · ·· │
│ # Security│                          │ 3.html     │                  │ ··· │ · · ··· │
└───────────┘                          └────────────┘                  └─────┴─────────┘

One command to HTML docs

awk -f hellodocs.awk -v title='Hello, Docs!' -v link='https://github.com/user/repo' README.md

Comparison

Features

HTML docs that will live within your application forever.

• Zero dependencies - just AWK, built into every *NIX system
• Single file
• Cross-platform - Linux, macOS, BSD, Windows (WSL)
• Offline-first
• No CSS, JS, IMG
• Frameset navigation
• Contenteditable code blocks for easy code copying
• Auto-nav from ## and ### headers
• MD tables, lists, code blocks support

Live demo

System requirements

AWK is a scripting language designed for text processing and data extraction, developed in 1977 and embedded in most Linux distributions. It natively runs in GitHub Actions and Docker without any additional installation steps.

hellodocs is known to work on many POSIX-compliant systems, including but not limited to:

• GNU/Linux
• macOS
• *BSD
• Android (through Termux)
• Windows (through WSL, Cygwin, or MSYS2)

Browsers:

• Chrome 20+
• Firefox 15+
• Safari 6+
• Edge (all versions)
• Internet Explorer 10+
• Opera 12+

Installation

You can embed hellodocs directly into your software by downloading or cloning it, or follow the Integration steps to include it in your workflow.

Direct download

curl -O https://raw.githubusercontent.com/tirrenotechnologies/hellodocs/master/hellodocs.awk

Or using wget:

wget https://raw.githubusercontent.com/tirrenotechnologies/hellodocs/master/hellodocs.awk

From Git

git clone https://github.com/tirrenotechnologies/hellodocs.git
cd hellodocs

Or download ZIP and extract.

Usage

Run this command to generate your HTML docs.

awk -f hellodocs.awk -v title='Hello, Docs!' -v link='https://github.com/user/repo' README.md

Markdown syntax

README.md example

Navigation is auto-generated from ## and ### headers:

# Project Name
Short description.

## Getting started
Introduction text.

### Installation
Installation instructions.

### Configuration
Configuration details.

## Usage
Usage examples.

## License
MIT

Output

Folder structure

my-project/
├── src/
├── hellodocs/
│   ├── hellodocs.awk
│   ├── README.md
│   ├── index.html           (generated)
│   ├── hellodocs-title.html (generated)
│   ├── hellodocs-nav.html   (generated)
│   ├── hellodocs-1.html     (generated)
│   └── ...
└── ...

Customization

Command-line variables:

Advanced: theming (edit hellodocs.awk to change):

Colors must be web-safe named colors.

Integration

hellodocs can be integrated into your build process to automatically regenerate documentation when your README.md changes. Add one of the following snippets to your project.

DEVELOPMENT.md repo → GitHub Action → /docs/index.html

GitHub Actions

Automatically generate documentation on every push to main/master.

Step 1: Create workflow directory

mkdir -p .github/workflows

Step 2: Create workflow file

Create .github/workflows/hellodocs.yml with the following content:

name: Generate Documentation
on:
  push:
    branches: [main, master]
  workflow_dispatch:  # Manual trigger
permissions:
  contents: write  # Required to commit generated docs
jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Pull latest changes
        run: git pull origin ${{ github.ref_name }}

      - name: Create docs directory
        run: mkdir -p docs

      - name: Download source documentation
        run: |
          curl -fsSL --max-time 30 -o docs/README.md https://raw.githubusercontent.com/YOUR_ORG/YOUR_REPO/master/README.md

      - name: Download hellodocs
        run: |
          curl -fsSL --max-time 30 -o docs/hellodocs.awk https://raw.githubusercontent.com/tirrenotechnologies/hellodocs/refs/heads/master/hellodocs.awk

      - name: Verify hellodocs (basic sanity check)
        run: |
          head -1 docs/hellodocs.awk | grep -q '^#' || exit 1
          grep -q 'function inline_fmt' docs/hellodocs.awk || exit 1
          grep -q 'function html_head' docs/hellodocs.awk || exit 1

      - name: Generate HTML documentation
        run: |
          cd docs
          awk -f hellodocs.awk -v title='Hello, Docs!' -v link='https://github.com/YOUR_ORG/YOUR_REPO' README.md

      - name: Cleanup source files
        run: |
          rm -f docs/hellodocs.awk
          rm -f docs/README.md

      - name: Commit and push generated docs
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add docs/
          if git diff --staged --quiet; then
            echo "No changes to commit"
          else
            git commit -m "hellodocs: regenerate documentation"
            git push
          fi

Step 3: Customize the workflow

Change these values to match your project:

Step 4: Trigger the workflow

Push to main/master branch, or manually trigger via: Actions → Generate Documentation → Run workflow

Output structure:

docs/
├── hellodocs.awk
├── README.md
├── index.html                  (generated)
├── hellodocs-title.html        (generated)
├── hellodocs-nav.html          (generated)
├── hellodocs-1.html            (generated)
└── ...

Makefile

Allows running make docs to regenerate documentation locally.

docs:
  cd docs && awk -f hellodocs.awk -v title='Hello, Docs!' -v link='https://github.com/user/repo' README.md

npm (package.json) allows running npm run docs in Node.js projects.

"scripts": {
  "docs": "cd docs && awk -f hellodocs.awk -v title=\"Hello, Docs!\" -v link=\"https://github.com/user/repo\" README.md"
}

Dockerfile generates documentation during container build, embedding docs into your Docker image.

FROM php:8.2-apache
COPY . /var/www/html/
RUN cd /var/www/html/docs && \
    awk -f hellodocs.awk -v title='Hello, Docs!' -v link='https://github.com/user/repo' README.md

Security

After generating documentation, remove the source files:

rm hellodocs.awk README.md

Troubleshooting

Contribution

Contributions are welcome. The goal of hellodocs is to provide documentation that any browser can render five years ago, tomorrow, and decades from now.

Please respect the project constraints: single file (everything in hellodocs.awk), pure POSIX-compatible AWK with no specific extensions, no external dependencies, no JavaScript, no CSS, no inline styles, web-safe named colors only (lavender, gainsboro, etc.), frameset-based navigation.

Found a mistake?

If you have found a mistake in the documentation, no matter how large or small, please let us know by creating a new issue in the hellodocs repository.

License

MIT License. Free to use, modify, and distribute.

't'