microdocs 1.2.1
Transform your Markdown files into a self-contained HTML documentation site.
Requires Python: >=3.11

# Microdocs

[![PyPI](https://img.shields.io/pypi/v/microdocs)](https://pypi.org/project/microdocs/)
[![Test](https://github.com/bartTC/microdocs/actions/workflows/test.yml/badge.svg)](https://github.com/bartTC/microdocs/actions/workflows/test.yml)
[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/microdocs/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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.

## 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](https://tscanlin.github.io/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](https://barttc.github.io/microdocs/)
- **Tailwhip Documentation** - [barttc.github.io/tailwhip](https://barttc.github.io/tailwhip/)

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

## Installation

### Using uv (recommended)

```bash
uvx microdocs
```

### Using pip

```bash
pip install microdocs
```

## Quick Start

Convert your README and CHANGELOG to HTML:

```bash
uvx microdocs README.md CHANGELOG.md
```

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

## Usage Examples

### Basic Usage

```bash
# 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

```bash
# 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:

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

**[See full GitHub Actions documentation →](ACTION.md)**

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

```bash
# 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 →](templates_src/TEMPLATES.md)**

## File Support

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