Microdocs
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)
uvx microdocs
Using pip
pip install microdocs
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