diff --git a/docs/user/index.rst b/docs/user/index.rst index 92c9b626ea2..ab25a0c7128 100644 --- a/docs/user/index.rst +++ b/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 diff --git a/docs/user/subprojects.rst b/docs/user/subprojects.rst index fd01b6a7854..3e8f70d389a 100644 --- a/docs/user/subprojects.rst +++ b/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 ---------------------------- diff --git a/docs/user/url-path-prefixes.rst b/docs/user/url-path-prefixes.rst new file mode 100644 index 00000000000..e118b986977 --- /dev/null +++ b/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 + - ``///`` + * - Single version project + - ``/`` + * - Subproject (multi-version) + - ``/projects////`` + * - Subproject (single version) + - ``/projects//`` + +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 ` + 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 ` + 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