readthedocs
[WIP] Document custom prefixes feature for projects and subprojects
- [x] Understand the internal documentation for custom path prefixes (readthedocs/proxito/README.rst)
- [x] Study the user documentation structure and style
- [x] Create a new user-facing documentation page for URL path prefixes feature
- [x] Add the new page to the documentation index (in Hosting documentation section)
- [x] Update subprojects.rst to reference the new URL customization feature
- [x] Run documentation builds to verify the changes
- [x] Run code review and address feedback
- [x] Run security check (codeql_checker - no code changes to analyze)
Original prompt
This section details on the original issue you should resolve
<issue_title>Proxito: document custom prefixes feature</issue_title> <issue_description>## What's the problem this feature will solve?
Custom prefixes for projects and subprojects were implemented in https://github.com/readthedocs/readthedocs.org/pull/10156, but we never documented them publicly. We have some internal docs about it in https://github.com/readthedocs/readthedocs.org/blob/main/readthedocs/proxito/README.rst#custom-path-prefixes.
We mention this feature in our pricing page (https://about.readthedocs.com/pricing/).
URL customization - Fine tune URLs used for your projects
We should link to our documentation from there with all the use cases this feature solves (proxying, removing or changing the "/projects" prefix).
There is also the discussion if we should expose this to users or manually handle this via support.
Front conversations</issue_description>
<agent_instructions>Write a user-facing documentation page for this feature. Talk about what it can do, and just mention you need to talk with support to start. Use the internal doc as a reference, but make it more simple and less technical for user-facing stuff. Ensure you put some good examples in the doc. </agent_instructions>
Comments on the Issue (you are @copilot in this section)
@agjohnson Yeah, I wouldn't mind exposing control of this as a beta feature/admin page as we are documenting it. Controlling this on behalf of users is tricky and requires scheduling changes and some back and forth. If users have this control they can remedy problems quicker.@humitos I had a customer asking to remove the `/projects/` part from the URL. It would be good to work on exposing this feature more in the UI so it can auto-sell itself when people see it as disabled from lower plans.If they decided to pay for the Pro Plan, I will need to do this manually for them since they don't have a way to do it by themselves yet.</comment_new> <comment_new>
We are writing a blog post to promote this feature in https://github.com/readthedocs/website/pull/356 but it seems we don't have documentation for the feature yet.</comment_new> <comment_new>@humitos @stsewd That blog post isn't related to this feature, but to the ability of changing the version slug.</comment_new>
- Fixes readthedocs/readthedocs.org#11324
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.
Documentation build overview
📚 docs | 🛠️ Build #30573280 | 📁 Comparing 94fd4abb1afebf92cd4bdb69c5247f14a786484f against latest (92b69eb68fc7f2e0dee444508fe87731724d2de4)
Show files changed (2 files in total): 📝 1 modified | ➕ 1 added | ➖ 0 deleted
| File | Status |
|---|---|
| subprojects.html | 📝 modified |
| url-path-prefixes.html | ➕ added |
![read-the-docs-community[bot] avatar](https://avatars.githubusercontent.com/in/1156917?v=4 "Published by a pub.dev verified publisher"){kind=small}
@copilot Try again
I've created a new documentation page for the custom URL path prefixes feature in commit 94fd4ab. The documentation includes:
- Explanation of what URL path prefixes are and their default patterns
- Use cases (proxying, removing /projects/ prefix, organizing docs)
- A clear example showing before/after URLs
- Instructions to contact support for enabling the feature
- Cross-references to related docs (subprojects, custom domains, versioning schemes)
I also added a seealso reference in subprojects.rst pointing to the new URL customization feature.
[!WARNING]
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
blog.readthedocs.com
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)dev.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)docs.djangoproject.com
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)docs.jupyter.org
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)docs.poliastro.space
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)docs.python.org
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)docs.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)executablebooks.org
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)ipyleaflet.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)ipywidgets.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)jupyterbook.org
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)jupytext.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)myst-nb.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)myst-parser.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)nbsphinx.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)rst-to-myst.readthedocs.io
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)www.sphinx-doc.org
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)www.writethedocs.org
- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html(dns block)- Triggering command:
/home/REDACTED/.local/bin/sphinx-build sphinx-build -b html -d _build/user/doctrees -T -j auto -W . _build/user/html g/readthedocs.org(dns block)If you need me to access, download, or install something from one of these locations, you can either:
- Configure Actions setup steps to set up my environment, which run before the firewall is enabled
- Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)