[WIP] Document custom prefixes feature for projects and subprojects

docs/user/index.rst

@@ -46,6 +46,7 @@ Read the Docs: documentation simplified
    /localization
    /versioning-schemes
    /custom-domains
+   /url-path-prefixes
    /doc-notifications
    /canonical-urls
    /reference/cdn

docs/user/subprojects.rst

@@ -62,6 +62,12 @@ When you add a subproject,
 the subproject will not be directly available anymore from its own domain.
 For instance, ``example-project-plugin.readthedocs.io/`` will redirect to ``example-project.readthedocs.io/projects/plugin``.
 
+.. seealso::
+
+   :doc:`/url-path-prefixes`
+      On |com_brand| Pro plans and higher,
+      you can customize the ``/projects/`` prefix or remove it entirely.
+
 Custom domain on subprojects
 ----------------------------
 

docs/user/url-path-prefixes.rst

@@ -0,0 +1,119 @@
+URL path prefixes
+=================
+
+URL path prefixes allow you to customize the URL structure of your documentation,
+giving you more control over how your documentation is organized and presented.
+
+This is a |com_brand| feature available on Pro and higher plans.
+Contact support to enable custom URL path prefixes for your project.
+
+.. contents::
+   :local:
+   :depth: 2
+
+What are URL path prefixes?
+---------------------------
+
+By default, Read the Docs serves documentation from the following URL patterns:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Project type
+     - Default URL pattern
+   * - Multi-version project
+     - ``/<language>/<version>/<filename>``
+   * - Single version project
+     - ``/<filename>``
+   * - Subproject (multi-version)
+     - ``/projects/<subproject-alias>/<language>/<version>/<filename>``
+   * - Subproject (single version)
+     - ``/projects/<subproject-alias>/<filename>``
+
+URL path prefixes let you customize these URL patterns by:
+
+* Adding a prefix to your project's documentation URLs
+* Changing or removing the ``/projects/`` prefix used for subprojects
+
+Use cases
+---------
+
+Here are some common scenarios where custom URL path prefixes are useful:
+
+Proxying documentation behind your main website
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to serve your documentation as part of your main website
+(for example, at ``https://example.com/docs/``),
+you can configure your web server to proxy requests to Read the Docs
+and use a custom prefix of ``/docs/`` to match.
+
+Removing the ``/projects/`` prefix from subproject URLs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, subprojects are served from URLs like
+``https://docs.example.com/projects/plugin/en/latest/``.
+You can change this prefix to something shorter or remove it entirely,
+so your subproject is served from ``https://docs.example.com/plugin/en/latest/``.
+
+Organizing documentation with meaningful URL paths
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use prefixes to create a more meaningful URL structure.
+For example, you could use ``/api/`` for API documentation
+and ``/guides/`` for user guides.
+
+Example
+-------
+
+Let's say you have the following projects:
+
+* ``example-docs``: main project
+* ``example-docs-es``: Spanish translation of the main project
+* ``example-plugin``: subproject of example-docs
+* ``example-plugin-es``: Spanish translation of the plugin
+
+With the default URL structure, they are served from:
+
+* ``https://docs.example.com/en/latest/`` (main project, English)
+* ``https://docs.example.com/es/latest/`` (main project, Spanish)
+* ``https://docs.example.com/projects/plugin/en/latest/`` (subproject, English)
+* ``https://docs.example.com/projects/plugin/es/latest/`` (subproject, Spanish)
+
+After configuring a custom prefix of ``/docs/`` for the main project
+and changing the subproject prefix to ``/libs/``, the URLs become:
+
+* ``https://docs.example.com/docs/en/latest/``
+* ``https://docs.example.com/docs/es/latest/``
+* ``https://docs.example.com/libs/plugin/en/latest/``
+* ``https://docs.example.com/libs/plugin/es/latest/``
+
+Getting started
+---------------
+
+URL path prefix customization is a |com_brand| feature.
+To enable this feature for your project:
+
+#. Ensure you have a Pro plan or higher subscription.
+#. Contact :doc:`Read the Docs support </support>`
+   with your project name and desired URL structure.
+#. Our support team will configure the custom prefixes for your project.
+
+.. tip::
+
+   When planning your URL structure,
+   consider how it will affect existing links to your documentation.
+   You may need to set up :doc:`redirects </user-defined-redirects>`
+   to ensure old URLs continue to work.
+
+.. seealso::
+
+   :doc:`/subprojects`
+      Learn how to set up subprojects and share a custom domain
+
+   :doc:`/custom-domains`
+      Configure a custom domain for your documentation
+
+   :doc:`/versioning-schemes`
+      Learn about different URL versioning schemes