Best practices for linking to your documentation

Once you start to publish documentation, external sources will inevitably link to specific pages in your documentation.

Sources of incoming links vary greatly depending on the type of documentation project that is published. They can include everything from old emails to GitHub issues, wiki articles, software comments, PDF publications, or StackOverflow answers. Most of these incoming sources are not in your control.

Read the Docs makes it easier to create and manage incoming links by redirecting certain URLs automatically and giving you access to define your own redirects.

In this article, we explain how our built-in redirects work and what we consider “best practice” for managing incoming links.

See also


Read more about how to handle versioned documentation and URL structures.


Overview of all the redirect features available on Read the Docs. Many of the redirect features are useful either for building external links or handling requests to old URLs.

How to use custom URL redirects in documentation projects

How to add a user-defined redirect, step-by-step. Useful if your content changes location!