mod_rewrite And Friends

A Guide to URL Manipulation and Mapping with the Apache HTTP Server, by Rich Bowen.

This book covers mod_rewrite in depth — regular expressions, RewriteRule, RewriteCond, RewriteMap, flags, logging, proxying, virtual hosts, access control, and more — along with the many other Apache httpd modules that can often do the job better.

Status

Version 3.9.0 — Published on Amazon (May 2026):

• Kindle edition
• Paperback edition
• Read online
• Website

Found a bug, typo, or have a suggestion? File an issue.

Building

The book is written in reStructuredText and built with Sphinx. No global install required — use uv to run in an ephemeral environment:

Quick Start (from scratch on a new Mac)

brew install uv librsvg
brew install mactex-no-gui     # optional, for PDF output
brew install calibre            # optional, for Kindle .azw3
./build.sh

Prerequisites

Required (for HTML and ePub):

• Python 3.8+
• uv (recommended) — or install Sphinx globally with pip install sphinx
• librsvg — provides rsvg-convert for SVG→PNG diagram conversion: brew install librsvg

Optional (for PDF output only):

• A LaTeX distribution with latexmk and pdflatex:

  OS	Install command
  macOS	brew install mactex-no-gui
  Debian / Ubuntu	sudo apt install texlive-full latexmk
  Fedora / RHEL	sudo dnf install texlive-scheme-full latexmk
  Arch	sudo pacman -S texlive-most latexmk
  Windows	Install MiKTeX or TeX Live

Optional (for Kindle output):

• Calibre — provides ebook-convert for ePub → azw3 conversion:
  • macOS: brew install calibre
  • Other platforms: download from calibre-ebook.com

If LaTeX is not installed, build.sh will still generate HTML and ePub successfully and skip the PDF step.

Installing uv:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

HTML

uv run --with sphinx -- sphinx-build -b html -d _build/doctrees . _build/html

Open _build/html/index.html in your browser to view.

ePub

uv run --with sphinx -- sphinx-build -b epub -d _build/doctrees . _build/epub

The ePub file will be at _build/epub/mod_rewrite And Friends.epub.

PDF (via LaTeX)

uv run --with sphinx -- sphinx-build -b latex -d _build/doctrees . _build/latex
cd _build/latex && make

The PDF will be at _build/latex/mod_rewrite_and_friends.pdf.

Using Make

If you have Sphinx installed globally (or in a virtualenv), you can use the Makefile shortcuts:

make html
make epub
make latexpdf
make linkcheck   # verify external links
make clean       # remove all build output

All formats

./build.sh

This cleans the output directory and builds HTML, ePub, and PDF in one go.

What build.sh does

1. SVG→PNG conversion — runs python3 convert_svg.py, which calls rsvg-convert to render all SVG diagrams in images/ to 2x PNG (192 DPI). Skips files already up-to-date.
2. Clean — removes _build/
3. HTML — sphinx-build -b html
4. ePub — sphinx-build -b epub, then fix_epub_footnotes.py patches the XHTML for Kindle compatibility
5. Kindle (azw3) — Calibre's ebook-convert (if installed). Note: Amazon's Send-to-Kindle service accepts ePub directly.
6. PDF (standard) — sphinx-build -b latex → latexmk (if installed)
7. PDF (KDP 6×9) — same, but with KDP_PRINT=1 for paperback-ready interior

Outputs

Format	Location	Notes
HTML	_build/html/index.html	Deploy to mod-rewrite.org
ePub	_build/epub/mod_rewriteAndFriends.epub	Also the KDP eBook manuscript
Kindle	_build/mod_rewrite_and_friends.azw3	USB sideload only
PDF (screen)	_build/latex/mod_rewrite_and_friends.pdf	Letter-size
PDF (KDP)	_build/latex_kdp/mod_rewrite_and_friends.pdf	6×9 trade paperback

Publishing to KDP

• eBook: Upload the ePub (not PDF) to the KDP dashboard. Cover: JPEG, 1600×2560px, 72+ DPI, RGB.
• Paperback: Upload the KDP PDF. Cover: print-ready PDF at 300 DPI (generated separately). Spine width depends on page count (~0.002252 in/page on white paper).
• Updating a live book: Just upload new manuscript/cover files in KDP — it replaces the existing edition in-place.
• KDP emails sort to Mac Mail Writing/mod_rewrite folder.

Version Bumping

When releasing a new version, update all three of:

1. conf.py — version and release variables
2. README.md — version number in the Status section
3. CHANGES.rst — add an entry

Website (mod-rewrite.org)

Website source lives in site/. Deploy with site/publish.sh (pushes to fagin.rcbowen.com).

Git Remote

Pushed via matrim relay: rbowen@matrim:/home/rbowen/devel/modrewrite_book/

Structure

├── conf.py                 — Sphinx configuration
├── index.rst               — Master table of contents
├── build.sh                — Build all formats (SVG→PNG, HTML, ePub, PDF)
├── convert_svg.py          — SVG→PNG conversion (uses rsvg-convert)
├── fix_epub_footnotes.py   — Patches ePub XHTML for Kindle footnote rendering
├── Makefile                — Build targets
├── cover.jpg
├── images/                 — Figures (SVG sources + generated PNGs)
├── ml_research/            — 20-year mailing list synthesis (v3.9 backlog source)
├── site/                   — mod-rewrite.org website source
├── TODO.md                 — v3.9 backlog (prioritized from mailing list research)
└── chapters/
    ├── 00_preface.rst
    ├── 01_regex.rst        — Regular Expressions
    ├── 02_url_mapping.rst  — URL Mapping
    ├── 03_mod_rewrite.rst  — Introduction to mod_rewrite
    ├── 04_rewriterule.rst  — RewriteRule
    ├── 05_rewrite_logging.rst — Rewrite Logging
    ├── 06_rewrite_flags.rst   — RewriteRule Flags
    ├── 07_rewritecond.rst  — RewriteCond
    ├── 08_rewritemap.rst   — RewriteMap
    ├── 09_proxy.rst        — Proxying with mod_rewrite
    ├── 10_vhosts.rst       — Virtual Hosts
    ├── 11_access.rst       — Access Control
    ├── 12_configurable_configuration.rst — Conditional Configuration
    ├── 13_content_munging.rst — Content Munging Modules
    ├── 14_recipes.rst      — Recipes
    ├── epigraphs.rst       — Chapter epigraphs
    └── glossary.rst

Dependencies Summary

Tool	Purpose	Install
Python 3.8+	Sphinx, scripts	(system)
uv	Ephemeral Sphinx env	brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
librsvg	SVG→PNG (rsvg-convert)	brew install librsvg
LaTeX (texlive)	PDF output	brew install mactex-no-gui
Calibre	ePub→azw3	brew install calibre

License

Copyright © 2013–2026 Rich Bowen.

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.