Version-aware documentation on ReadTheDocs without breaking search
Control which documentation version users see and search on ReadTheDocs using version-aware configuration and Sphinx conditionals.
Loading…
ReadMeFeed / Community knowledge
#sphinx
Real questions. Useful conversations. Find the people who know your stack.
readthedocsReadTheDocs v2 Configuration: Pinning Builds, Adding Formats, and Migrating from Legacy YAML
Learn how to migrate to ReadTheDocs v2 config, pin build images and Python versions, add PDF/EPUB output, use conda for system dependencies, and avoid common pitfalls like legacy file conflicts and missing directory changes.
Choosing the Right Build Trigger for ReadTheDocs: Webhooks vs. Manual Builds
Choose the right build trigger for ReadTheDocs: webhook‑based automatic builds or manual/CI‑triggered builds. A practical guide with example config, trade‑offs, and a step‑by‑step Sphinx setup.
Managing Multiple Docs Versions in ReadTheDocs: Flyout Menu & Version Control Explained
Learn how to configure ReadTheDocs to host stable, latest, and release‑tagged documentation with a flyout menu. A practical guide that covers configuration files, alias mapping, and trade‑offs.
One Repo, Many Docs: How Read the Docs Turns Git Tags Into Versioned Documentation
Read the Docs builds one documentation site per Git branch or tag, giving you stable/latest/release URLs for free. Here's how the versioning model works, with a worked tag-push example and the trade-offs to plan for.
Stop Reviewing Docs by Diff: Use Read the Docs Pull Request Previews
Reviewing docs by diff hides rendering problems. Read the Docs pull request preview builds render a temporary site for each PR and post a status check, letting reviewers see layout and links before merge.
Choosing a Versioning Strategy for Read the Docs: Branches vs Tags in Practice
Read the Docs versions map to Git refs, not semantic versions. This post walks through choosing between branch-per-release and tag-per-release strategies, shows how to pin "stable" to a major series, and lists the limitations (build minutes, private repos, custom domains) that affect real projects.
Single Version or Multiple Versions on Read the Docs: A Decision Guide
Decide between single-version and multi-version docs on Read the Docs: constraints, trade-offs, a comparison table, a .readthedocs.yaml example, and verification steps.
Brand Your Docs on ReadTheDocs: Custom CSS for the RTD Sphinx Theme
Give your ReadTheDocs documentation a brand‑consistent look by adding a custom CSS file. The post walks through creating <code>custom.css</code>, linking it in <code>conf.py</code>, testing locally, and handling maintenance pitfalls.