Document custom prefixes feature for projects and subprojects (#12637)
- [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] Add seealso link from versioning-schemes.rst to reference the new
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)
- [x] Remove local table of contents directive
- [x] Split complex example into two simpler, separate cases
- [x] Clean up to single commit with all PR changes (4 files, 133 lines)
- [x] Address @humitos feedback on documentation structure
<!-- START COPILOT CODING AGENT SUFFIX -->
<details>
<summary>Original prompt</summary>
>
> ----
>
> *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.
>
> <img src="https://front.com/assets/img/favicons/favicon-32x32.png"
height="16" width="16" alt="Front logo" /> [Front
conversations](https://app.frontapp.com/open/top_1qdb47)</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)
>
> <comments>
> <comment_new><author>@agjohnson</author><body>
> 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.</body></comment_new>
> <comment_new><author>@humitos</author><body>
> 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.</body></comment_new>
> <comment_new><author>@humitos</author><body>
> 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.</body></comment_new>
> <comment_new><author>@stsewd</author><body>
> That blog post isn't related to this feature, but to the ability of
changing the version slug.</body></comment_new>
> </comments>
>
</details>
- Fixes readthedocs/readthedocs.org#11324
<!-- START COPILOT CODING AGENT TIPS -->
---
💡 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](https://gh.io/copilot-coding-agent-tips) in the docs.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: humitos <244656+humitos@users.noreply.github.com>
readthedocs.org
64136526 - Document custom prefixes feature for projects and subprojects (#12637)
