docs-output-filter
Filter documentation build output to show only what matters: warnings and errors.
Works with MkDocs and Sphinx (including sphinx-autobuild, Jupyter Book, myst-nb). Includes an MCP server for AI code assistant integration (Claude Code, etc.).
Before & After
| ❌ Raw build output (43 lines) | ✅ Filtered output (15 lines) |
|---|---|
|
|
Installation
# Run directly (no install needed)
uvx docs-output-filter -- mkdocs build
# Or install permanently
uv tool install docs-output-filter
# Or with pip
pip install docs-output-filter
Usage
# Wrapper mode (recommended) — just prefix your build command
docs-output-filter -- mkdocs build
docs-output-filter -- mkdocs serve --livereload
docs-output-filter -- sphinx-autobuild docs _build/html
# Pipe mode — traditional Unix pipe
mkdocs build 2>&1 | docs-output-filter
sphinx-build docs _build 2>&1 | docs-output-filter
# Process a remote build log (e.g., ReadTheDocs)
docs-output-filter --url https://app.readthedocs.org/projects/myproject/builds/12345/
Tip: Wrapper mode (
--) is the easiest way to use docs-output-filter. It runs the command for you, automatically captures both stdout and stderr, and fixes buffering issues with sphinx-autobuild. No2>&1needed.
Note: If using pipe mode,
2>&1is important — Sphinx writes warnings to stderr. Without it, warnings bypass the filter.
Note: Use
--livereloadwithmkdocs servedue to a Click 8.3.x bug.
Features
| Feature | Description |
|---|---|
| Multi-tool support | MkDocs and Sphinx with auto-detection |
| Filtered output | Shows WARNING and ERROR messages, hides routine INFO |
| Code blocks | Syntax-highlighted code for markdown_exec and myst-nb errors |
| Location info | File, line number, session name, warning codes |
| Streaming mode | Real-time output for mkdocs serve / sphinx-autobuild with rebuild detection |
| Interactive mode | Toggle between raw/filtered with keyboard (-i) |
| Remote logs | Fetch and parse build logs from ReadTheDocs and other CI |
| MCP server | API for AI code assistants like Claude Code |
Options
| Flag | Description |
|---|---|
-- COMMAND |
Run command as subprocess (recommended, no 2>&1 needed) |
-v, --verbose |
Show full tracebacks and code blocks |
-e, --errors-only |
Hide warnings, show only errors |
--no-color |
Disable colored output |
--raw |
Pass through unfiltered build output |
-i, --interactive |
Toggle raw/filtered with keyboard |
--url URL |
Fetch and process a remote build log |
--tool mkdocs|sphinx|auto |
Force build tool detection (default: auto) |
--share-state |
Write state for MCP server integration |
MCP Server (for AI Assistants)
Enable AI code assistants to access build issues:
# Terminal 1: Run build tool with state sharing
docs-output-filter --share-state -- mkdocs serve --livereload
# Terminal 2: Add MCP server to Claude Code (if installed)
claude mcp add --scope user --transport stdio docs-output-filter -- docs-output-filter --mcp --watch
# Or with uvx (no install needed)
claude mcp add --scope user --transport stdio docs-output-filter -- uvx docs-output-filter --mcp --watch
Documentation
Full documentation: https://ianhuntisaak.com/docs-output-filter/
Development
git clone https://github.com/ianhi/docs-output-filter
cd docs-output-filter
uv sync
uv run pre-commit install
uv run pytest
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for docs-output-filter 0.3.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| docs_output_filter-0.3.4.tar.gz | 35.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| docs_output_filter-0.3.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 78.6 kB
Release files / docs_output_filter-0.3.4.tar.gz
| Download URL | docs_output_filter-0.3.4.tar.gz |
|---|---|
| Size | 35.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ae1a4eae1f3c4225fec39f63be2737804246f2f9390bdfaf84bc4a11c8cd113e
|
|
BLAKE2b-256 checksum How to use checksums |
ac21c8e14179f66bff592b5241fa42583982ef5ae13d653852ce1c6b6a2ad6da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 5, 2026.
Transparency logRelease files / docs_output_filter-0.3.4-py3-none-any.whl
| Download URL | docs_output_filter-0.3.4-py3-none-any.whl |
|---|---|
| Size | 43.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
271d80b782f97980003e1042a8ccda7027aa94857fd4fb7d68f237cf13bffaa4
|
|
BLAKE2b-256 checksum How to use checksums |
05ba6090ddc954a093729c2233d4e100012e390a100e93a957e0abf1c8fbb8d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 5, 2026.
Transparency log
