GitHub - bartTC/microdocs: Transform your Markdown files into a self-contained HTML documentation site.

Transform your Markdown files into a self-contained HTML documentation site.

Microdocs is a Python tool that converts Markdown files (like README.md and CHANGELOG.md) into a beautiful, single-page HTML documentation site with navigation, table of contents, and syntax highlighting.

✨ Zero Configuration Required - Just point it at your Markdown files and get a beautiful documentation site. No config files, no setup, no dependencies to install.

Features

• Simple & Fast - Convert multiple Markdown files to HTML with a single command
• Self-Contained - Generates a single HTML file with all styles embedded (only tocbot loaded from CDN)
• Beautiful UI - Modern, clean design with Tailwind CSS and Alpine.js
• Smart Navigation - Single-page app with tab-based navigation between sections
• Automatic Table of Contents - Generated with tocbot with active heading tracking
• Dark Mode - Automatic system preference detection with manual toggle
• Syntax Highlighting - Code blocks with Pygments highlighting for both light and dark themes
• Responsive Design - Optimized layouts for mobile and desktop
• Zero Configuration - Works out of the box with sensible defaults
• Customizable - Use your own HTML templates and CSS styles

Examples

See Microdocs in action with these live documentation sites:

• Microdocs Documentation - barttc.github.io/microdocs
• Tailwhip Documentation - barttc.github.io/tailwhip

Both sites are generated from Markdown files using Microdocs with the default template.

Installation

Using uv (recommended)

Using pip

Quick Start

Convert your README and CHANGELOG to HTML:

uvx microdocs README.md CHANGELOG.md

This creates index.html in your current directory. Open it in your browser!

Usage Examples

Basic Usage

# Convert a single file
uvx microdocs README.md

# Convert multiple files
uvx microdocs README.md CHANGELOG.md CONTRIBUTING.md

# Specify output file
uvx microdocs README.md -o docs/index.html

# Set custom title
uvx microdocs README.md --title "My Project Docs"

# Add repository link
uvx microdocs README.md --repo-url https://github.com/user/repo

Advanced Usage

# Use custom template
uvx microdocs README.md -t custom-template.html

# Combine options
uvx microdocs README.md CHANGELOG.md \
  -o dist/index.html \
  --title "My Project" \
  --repo-url https://github.com/user/repo \
  -t templates/custom.html

GitHub Actions

Automatically deploy your documentation to GitHub Pages:

- name: Build and deploy documentation
  uses: bartTC/microdocs@v1
  with:
    files: |
      README.md
      CHANGELOG.md
    title: 'My Project'

See full GitHub Actions documentation →

Template System

Microdocs uses Jinja2 templates with Vite-based builds. The default template includes:

• Responsive Layout - Two-column design with main content and TOC sidebar
• Page Navigation - Tab-like navigation between sections
• Sticky TOC - Table of contents that follows you as you scroll
• Dark Mode Ready - Automatic theme detection with manual toggle

Using Custom Templates

# Use built-in template by name
uvx microdocs README.md -t default

# Use custom template file
uvx microdocs README.md -t /path/to/custom-template.html

See full template development guide →

File Support

• Markdown files (.md, .markdown) - Full markdown processing with extensions
• Plain text files - Displayed with preserved formatting