diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..b353dd9
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,84 @@
+name: Docs
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - 'book/**'
+ - 'docs/**'
+ - '.github/workflows/docs.yml'
+ - 'CHANGELOG.md'
+ - 'CONTRIBUTING.md'
+ - 'README.md'
+ pull_request:
+ paths:
+ - 'book/**'
+ - 'docs/**'
+ - '.github/workflows/docs.yml'
+ - 'CHANGELOG.md'
+ - 'CONTRIBUTING.md'
+ - 'README.md'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: docs-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: dtolnay/rust-toolchain@stable
+
+ # Bump cache key when any tool version in the install step changes
+ - name: Cache mdbook binaries
+ id: cache-mdbook
+ uses: actions/cache@v5
+ with:
+ path: ~/.cargo/bin/mdbook*
+ key: mdbook-v2-${{ hashFiles('.github/workflows/docs.yml') }}
+
+ - name: Install mdbook and plugins
+ if: steps.cache-mdbook.outputs.cache-hit != 'true'
+ run: |
+ cargo install \
+ mdbook@0.4.40 \
+ mdbook-linkcheck@0.7.7 \
+ mdbook-toc@0.14.2 \
+ mdbook-admonish@1.18.0 \
+ mdbook-mermaid@0.14.1
+
+ - name: Build book
+ run: mdbook build book
+
+ - name: Upload Pages artifact
+ if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+ uses: actions/upload-pages-artifact@v4
+ with:
+ path: target/book/html
+
+ - name: Verify build (PR)
+ if: github.event_name == 'pull_request'
+ run: |
+ test -f target/book/html/index.html
+ test -s target/book/html/index.html
+ echo "Build OK"
+
+ deploy:
+ needs: build
+ if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+ runs-on: ubuntu-latest
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index 416c1dd..4aa5334 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,6 +27,9 @@ result-*
# Ruff cache (leftover from Python tooling)
.ruff_cache/
+# mdBook build output
+/target/book/
+
# integration test artifacts
tests/integration/level1/fixtures/*.flow
tests/integration/level1/out/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ea1c55c..2d855a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,3 @@
-# Changelog
-
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 81fa319..d50a310 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,3 @@
-# Contributing — Local Testing Guide
-
This document covers how to run the three test tracks locally.
## Prerequisites
diff --git a/Cargo.toml b/Cargo.toml
index 7f3d875..045a156 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -17,6 +17,7 @@ exclude = [
"docs/demo.mp4", ".github/**", "scripts/**",
"flake.nix", "flake.lock", ".envrc", ".direnv/**",
".sisyphus/**", ".ruff_cache/**",
+ "book/**", "docs/**",
]
[[bin]]
diff --git a/README.md b/README.md
index ab7bffe..1ac5ef1 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ A Rust rewrite of [mitmproxy2swagger](https://github.com/alufers/mitmproxy2swagg
[](https://crates.io/crates/mitm2openapi)
[](https://crates.io/crates/mitm2openapi)
[](https://docs.rs/mitm2openapi)
+[](https://arkptz.github.io/mitm2openapi/)
[](LICENSE)
@@ -39,17 +40,13 @@ Credit to [@alufers](https://github.com/alufers) for the original tool that pion
## Installation
-### From binary releases
-
-Download a pre-built binary from [GitHub Releases](https://github.com/Arkptz/mitm2openapi/releases).
-
-### From source
-
```bash
-cargo install --git https://github.com/Arkptz/mitm2openapi
+cargo install mitm2openapi
```
-## Quick Start
+Or download a pre-built binary from [GitHub Releases](https://github.com/Arkptz/mitm2openapi/releases).
+
+## Quick start
```bash
# 1. Capture traffic with mitmproxy
@@ -64,206 +61,13 @@ mitm2openapi discover -i capture.flow -o templates.yaml -p "https://api.example.
mitm2openapi generate -i capture.flow -t templates.yaml -o openapi.yaml -p "https://api.example.com"
```
-### Skip the manual edit
-
-If you know which paths you care about up front, use `--exclude-patterns`
-and `--include-patterns` to let `discover` do the curation:
-
-```bash
-mitm2openapi discover \
- -i capture.flow -o templates.yaml -p "https://api.example.com" \
- --exclude-patterns '/static/**,/images/**,*.css,*.js,*.svg' \
- --include-patterns '/api/**,/v2/**'
-
-mitm2openapi generate \
- -i capture.flow -t templates.yaml -o openapi.yaml -p "https://api.example.com"
-```
-
-Paths matching `--include-patterns` are auto-activated (emitted without
-the `ignore:` prefix). Paths matching `--exclude-patterns` are dropped
-entirely. Everything else still gets `ignore:` for manual review.
-
-
-CLI Reference (click to expand)
-
-### `discover`
-
-Scan captured traffic and produce a templates file listing all observed endpoints.
-
-```
-mitm2openapi discover [OPTIONS] -i -o