PyPI Test Python Version License: MIT

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.

• 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

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.

uvx microdocs

pip install microdocs

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!

# 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

# 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

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 →

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

# 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 →

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