Skip to content

Commit 79178c6

Browse files
ericholscherericholscher
authored
Merge pull request #9266 from readthedocs/update-custom-domain-docs
Docs: update custom domains docs
2 parents 3e70b81 + 4415907 commit 79178c6

10 files changed

+211
-204
lines changed

‎docs/conf.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,8 @@
157157
hoverxref_domains = ["py"]
158158
hoverxref_roles = [
159159
"option",
160-
"doc",
160+
"doc", # Documentation pages
161+
"term", # Glossary terms
161162
]
162163
hoverxref_role_types = {
163164
"mod": "modal", # for Python Sphinx Domain

‎docs/user/canonical-urls.rst

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
Canonical URLs
2+
==============
3+
4+
A `canonical URL`_
5+
allows you to specify the preferred version of a web page to prevent duplicated content.
6+
They are mainly used by search engines to link users to the correct
7+
version and domain of your documentation.
8+
9+
If canonical URL's aren't used,
10+
it's easy for outdated documentation to be the top search result for various pages in your documentation.
11+
This is not a perfect solution for this problem,
12+
but generally people finding outdated documentation is a big problem,
13+
and this is one of the suggested ways to solve it from search engines.
14+
15+
.. _canonical URL: https://developers.google.com/search/docs/advanced/crawling/consolidate-duplicate-urls
16+
17+
How Read the Docs generates canonical URLs
18+
------------------------------------------
19+
20+
The canonical URL takes into account:
21+
22+
* The default version of your project (usually "latest" or "stable").
23+
* The canonical :doc:`custom domain </custom-domains>` if you have one,
24+
otherwise the default :ref:`subdomain <hosting:subdomain support>` will be used.
25+
26+
For example, if you have a project named ``example-docs``
27+
with a custom domain ``https://docs.example.com``,
28+
then your documentation will be served at ``https://example-docs.readthedocs.io`` and ``https://docs.example.com``.
29+
Without specifying a canonical URL, a search engine like Google will index both domains.
30+
31+
You'll want to use ``https://docs.example.com`` as your canonical domain.
32+
This means that when Google indexes a page like ``https://example-docs.readthedocs.io/en/latest/``,
33+
it will know that it should really point at ``https://docs.example.com/en/latest/``,
34+
thus avoiding duplicating the content.
35+
36+
.. note::
37+
38+
If you want your custom domain to be set as the canonical, you need to set ``Canonical: This domain is the primary one where the documentation is served from`` in the :guilabel:`Admin` > :guilabel:`Domains` section of your project settings.
39+
40+
Implementation
41+
--------------
42+
43+
The canonical URL is set in HTML with a ``link`` element.
44+
For example, this page has a canonical URL of:
45+
46+
.. code-block:: html
47+
48+
<link rel="canonical" href="https://docs.readthedocs.io/en/stable/canonical-urls.html" />
49+
50+
Sphinx
51+
~~~~~~
52+
53+
If you are using :doc:`Sphinx </intro/getting-started-with-sphinx>`,
54+
Read the Docs will set the value of the html_baseurl_ setting (if isn't already set) to your canonical domain.
55+
If you already have ``html_baseurl`` set, you need to ensure that the value is correct.
56+
57+
.. _html_baseurl: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_baseurl
58+
59+
Mkdocs
60+
~~~~~~
61+
62+
For :doc:`MkDocs </intro/getting-started-with-mkdocs>` this isn't done automatically,
63+
but you can use the site_url_ setting to set a similar value.
64+
65+
.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url
66+
67+
.. warning::
68+
69+
If you change your default version or canonical domain,
70+
you'll need to re-build all your versions in order to update their
71+
canonical URL to the new one.

‎docs/user/custom-domains.rst

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
Custom Domains
2+
==============
3+
4+
Custom domains allow you to serve your documentation from your own domain.
5+
This is great for maintaining a consistent brand for your documentation and application.
6+
7+
By default, your documentation is served from a Read the Docs :ref:`subdomain <hosting:subdomain support>` using the project's :term:`slug`:
8+
9+
* ``<slug>.readthedocs.io`` for |org_brand|
10+
* ``<slug>.readthedocs-hosted.com`` for |com_brand|.
11+
12+
For example if you import your project and it gets the :term:`slug` ``example-docs``, it will be served from ``https://example-docs.readthedocs.io``.
13+
14+
.. contents:: Contents
15+
:local:
16+
17+
Adding a custom domain
18+
----------------------
19+
20+
To setup your custom domain, follow these steps:
21+
22+
#. Go the :guilabel:`Admin` tab of your project.
23+
#. Click on :guilabel:`Domains`.
24+
#. Enter your domain.
25+
#. Mark the :guilabel:`Canonical` option if you want use this domain
26+
as your :doc:`canonical domain </canonical-urls>`.
27+
#. Click on :guilabel:`Add`.
28+
#. At the top of the next page you'll find the value of the DNS record that you need to point your domain to.
29+
For |org_brand| this is ``readthedocs.io``, and for :doc:`/commercial/index`
30+
the record is in the form of ``<hash>.domains.readthedocs.com``.
31+
32+
.. note::
33+
34+
For a subdomain like ``docs.example.com`` add a CNAME record,
35+
and for a root domain like ``example.com`` use an ANAME or ALIAS record.
36+
37+
By default, we provide a validated SSL certificate for the domain,
38+
managed by `Cloudflare <https://www.cloudflare.com/>`_.
39+
The SSL certificate issuance should happen within a few minutes,
40+
but might take up to one hour.
41+
See `SSL certificate issue delays`_ for more troubleshooting options.
42+
43+
As an example, our blog's DNS record looks like this:
44+
45+
.. prompt:: bash $, auto
46+
47+
$ dig +short CNAME blog.readthedocs.com
48+
readthedocs.io.
49+
50+
.. warning::
51+
52+
We don't support pointing subdomains or root domains to a project using A records.
53+
DNS A records require a static IP address and our IPs may change without notice.
54+
55+
56+
Removing a custom domain
57+
------------------------
58+
59+
To remove a custom domain:
60+
61+
#. Go the :guilabel:`Admin` tab of your project.
62+
#. Click on :guilabel:`Domains`.
63+
#. Click the :guilabel:`Remove` button next to the domain.
64+
#. Click :guilabel:`Confirm` on the confirmation page.
65+
66+
.. warning::
67+
68+
Once a domain is removed,
69+
your previous documentation domain is no longer served by Read the Docs,
70+
and any request for it will return a 404 Not Found!
71+
72+
Strict Transport Security (HSTS) and other custom headers
73+
---------------------------------------------------------
74+
75+
By default, we do not return a `Strict Transport Security header`_ (HSTS) for user custom domains.
76+
This is a conscious decision as it can be misconfigured in a not easily reversible way.
77+
For both |org_brand| and |com_brand|, HSTS and other custom headers can be set upon request.
78+
79+
We always return the HSTS header with a max-age of at least one year
80+
for our own domains including ``*.readthedocs.io``, ``*.readthedocs-hosted.com``, ``readthedocs.org`` and ``readthedocs.com``.
81+
82+
Please contact :doc:`support` if you want to add a custom header to your domain.
83+
84+
.. _Strict Transport Security header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
85+
86+
Multiple documentation sites as sub-folders of a domain
87+
-------------------------------------------------------
88+
89+
You may host multiple documentation repositories as **sub-folders of a single domain**.
90+
For example, ``docs.example.org/projects/repo1`` and ``docs.example.org/projects/repo2``.
91+
This is `a way to boost the SEO of your website <https://moz.com/blog/subdomains-vs-subfolders-rel-canonical-vs-301-how-to-structure-links-optimally-for-seo-whiteboard-friday>`_.
92+
93+
See :doc:`subprojects` for more information.
94+
95+
Troubleshooting
96+
---------------
97+
98+
SSL certificate issue delays
99+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100+
101+
The status of your domain validation and certificate can always be seen on the details page for your domain
102+
under :guilabel:`Admin` > :guilabel:`Domains` > :guilabel:`YOURDOMAIN.TLD (details)`.
103+
104+
Domains are usually validated and a certificate issued within minutes.
105+
However, if you setup the domain in Read the Docs without provisioning the necessary DNS changes
106+
and then update DNS hours or days later,
107+
this can cause a delay in validating because there is an exponential back-off in validation.
108+
109+
.. tip::
110+
111+
Loading the domain details in the Read the Docs dashboard and saving the domain again will force a revalidation.
112+
113+
Migrating from GitBook
114+
~~~~~~~~~~~~~~~~~~~~~~
115+
116+
If your custom domain was previously used in GitBook, contact GitBook support (via live chat in their website)
117+
to remove the domain name from their DNS Zone in order for your domain name to work with Read the Docs,
118+
else it will always redirect to GitBook.

‎docs/user/custom_domains.rst

-197
This file was deleted.

0 commit comments

Comments
 (0)