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 Read the Docs for Business feature available on Pro and higher plans. Contact support to enable custom URL path prefixes for your project.

What are URL path prefixes?

By default, Read the Docs serves documentation from the following URL patterns:

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 Read the Docs for Business feature. To enable this feature for your project:

  1. Ensure you have a Pro plan or higher subscription.

  2. Contact Read the Docs support with your project name and desired URL structure.

  3. 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 redirects to ensure old URLs continue to work.

See also

Subprojects

Learn how to set up subprojects and share a custom domain

Custom domains

Configure a custom domain for your documentation

URL versioning schemes

Learn about different URL versioning schemes