Skip to content

Commit e458023

Browse files
stsewdstsewd
committed
Docs: update custom domains docs
1 parent fddd885 commit e458023

8 files changed

+208
-203
lines changed

‎docs/user/canonical-urls.rst

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
Canonical URLs
2+
==============
3+
4+
Canonical URLs allow you to have consistent page URLs across all your domains.
5+
This is mainly useful for search engines,
6+
so that they can send users to the correct version and domain of your documentation.
7+
8+
The canonical URL is generated based on:
9+
10+
* The default version of your project (usually "latest" or "stable").
11+
* The canonical :doc:`custom domain </custom-domains>` if you have one,
12+
otherwise the default :ref:`subdomain <hosting:subdomain support>` will be used.
13+
14+
.. contents::
15+
:local:
16+
17+
Example
18+
-------
19+
20+
Fabric hosts their docs on Read the Docs,
21+
but they use their own domain ``http://docs.fabfile.org``.
22+
This means that Google will index both ``http://fabric-docs.readthedocs.io`` and
23+
``http://docs.fabfile.org`` for their documentation.
24+
25+
Fabric will want to set ``http://docs.fabfile.org`` as their canonical domain,
26+
this means that when Google indexes ``http://fabric-docs.readthedocs.io``,
27+
it will know that it should really point at ``http://docs.fabfile.org``.
28+
29+
Implementation
30+
--------------
31+
32+
If you are using :doc:`Sphinx </intro/getting-started-with-sphinx>`,
33+
Read the Docs will set the value of the html_baseurl_ setting (if isn't already set) to your canonical domain.
34+
35+
.. _html_baseurl: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_baseurl
36+
37+
For :doc:`MkDocs </intro/getting-started-with-mkdocs>` this isn't done automatically,
38+
but you can use the site_url_ setting.
39+
40+
.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url
41+
42+
If you look at the source code for the documentation built after you set your canonical URL,
43+
you should see a bit of HTML like this:
44+
45+
.. code-block:: html
46+
47+
<link rel="canonical" href="http://docs.fabfile.org/en/2.4/" />
48+
49+
.. note::
50+
51+
If you change your default version or canonical domain,
52+
you'll need to re-build all your versions in order to update their
53+
canonical URL to the new one.

‎docs/user/custom-domains.rst

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
Custom Domains
2+
==============
3+
4+
With custom domains you can serve your documentation from your own domain.
5+
By default your documentation is served from a Read the Docs :ref:`subdomain <hosting:subdomain support>`:
6+
``<slug>.readthedocs.io`` or ``<slug>.readthedocs-hosted.com``,
7+
for example ``https://pip.readthedocs.io``.
8+
9+
.. contents::
10+
:local:
11+
12+
Adding a custom domain
13+
----------------------
14+
15+
To setup your custom domain, follow these steps:
16+
17+
#. Go the :guilabel:`Admin` tab of your project.
18+
#. Click on :guilabel:`Domains`.
19+
#. Enter your domain.
20+
#. Mark the :guilabel:`Canonical` option if you want use this domain
21+
as your :doc:`canonical domain </canonical-urls>`.
22+
#. Click on :guilabel:`Add`.
23+
#. At the top of the next page you'll find the value of the CNAME record that you need to point your domain to.
24+
For |org_brand| this is ``readthedocs.io``, and for :doc:`/commercial/index`
25+
the record is in the form of ``<hash>.domains.readthedocs.com``.
26+
27+
.. note::
28+
29+
For a subdomain like ``docs.example.com`` add a CNAME record,
30+
and for a root domain like ``example.com`` use an ANAME or ALIAS record.
31+
32+
By default, we provide a validated SSL certificate for the domain,
33+
this service is provided by Cloudflare.
34+
The SSL certificate issuance can take about one hour,
35+
you can see the status of the certificate on the domain page in your project.
36+
37+
As an example, fabric's DNS record looks like this:
38+
39+
.. prompt:: bash $, auto
40+
41+
$ dig CNAME +short docs.fabfile.org
42+
readthedocs.io.
43+
44+
.. warning::
45+
46+
We don't support pointing subdomains or root domains to a project using A records.
47+
DNS A records require a static IP address and our IPs may change without notice.
48+
49+
Strict Transport Security
50+
-------------------------
51+
52+
By default, we do not return a `Strict Transport Security header`_ (HSTS) for user custom domains.
53+
This is a conscious decision as it can be misconfigured in a not easily reversible way.
54+
For both |org_brand| and |com_brand|, HSTS for custom domains can be set upon request.
55+
56+
We always return the HSTS header with a max-age of at least one year
57+
for our own domains including ``*.readthedocs.io``, ``*.readthedocs-hosted.com``, ``readthedocs.org`` and ``readthedocs.com``.
58+
59+
.. _Strict Transport Security header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
60+
61+
Legacy domains on |com_brand|
62+
-----------------------------
63+
64+
Some older setups configured a CNAME record pointing to
65+
``<organization-slug>.users.readthedocs.com``,
66+
these domains will continue to resolve.
67+
68+
Previously you were asked to add two records,
69+
this process has been simplified.
70+
If you have doubts about deleting some of the old records,
71+
please reach out to :ref:`support <support:user support>`.
72+
73+
Multiple documentation sites as sub-folders of a domain
74+
-------------------------------------------------------
75+
76+
You may host multiple documentation repositories as **sub-folders of a single domain**.
77+
For example, ``docs.example.org/projects/repo1`` and ``docs.example.org/projects/repo2``.
78+
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>`_.
79+
80+
See :doc:`subprojects` for more information.
81+
82+
Troubleshooting
83+
---------------
84+
85+
SSL certificate issue delays
86+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87+
88+
The status of your domain validation and certificate can always be seen on the details page for your domain
89+
under :guilabel:`Admin` > :guilabel:`Domains` > :guilabel:`YOURDOMAIN.TLD (details)`.
90+
91+
Domains are usually validated and a certificate issued within minutes.
92+
However, if you setup the domain in Read the Docs without provisioning the necessary DNS changes
93+
and then update DNS hours or days later,
94+
this can cause a delay in validating because there is an exponential back-off in validation.
95+
Loading the domain details in the Read the Docs dashboard and saving the domain again will force a revalidation.
96+
97+
Certificate authority authorization
98+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99+
100+
Certificate authority authorization (CAA) is a security feature that allows domain owners to limit
101+
which certificate authorities (CAs) can issue certificates for a domain.
102+
This is done by setting CAA DNS records for your domain.
103+
104+
The readthedocs domains that you'll point your domains to already
105+
have the proper CAA records.
106+
107+
.. prompt:: bash $, auto
108+
109+
$ dig +short readthedocs.io CAA
110+
0 issue "digicert.com; cansignhttpexchanges=yes"
111+
0 issuewild "digicert.com; cansignhttpexchanges=yes"
112+
0 issue "comodoca.com"
113+
0 issue "letsencrypt.org"
114+
0 issuewild "comodoca.com"
115+
0 issuewild "letsencrypt.org"
116+
117+
.. prompt:: bash $, auto
118+
119+
$ dig +short 0acba22b.domains.readthedocs.com CAA
120+
proxy-fallback.readthedocs-hosted.com.
121+
0 issue "digicert.com"
122+
0 issue "comodoca.com"
123+
0 issue "letsencrypt.org"
124+
125+
In case that there are CAA records for your domain that do not allow the certificate authorities that Read the Docs uses,
126+
you may see an error message like ``pending_validation: caa_error: YOURDOMAIN.TLD``
127+
in the Read the Docs dashboard for your domain.
128+
You will need to update your CAA records to allow us to issue the certificate.
129+
130+
We use Cloudflare, which uses Digicert as a CA. See the `Cloudflare CAA FAQ`_ for details.
131+
132+
.. _Cloudflare CAA FAQ: https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ
133+
134+
.. note::
135+
136+
If your custom domain was previously used in GitBook, contact GitBook support (via live chat in their website)
137+
to remove the domain name from their DNS Zone in order for your domain name to work with Read the Docs,
138+
else it will always redirect to GitBook.

‎docs/user/custom_domains.rst

-197
This file was deleted.

‎docs/user/faq.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ http://docs..org/projects/kombu/en/latest/
141141

142142
You can add subprojects in the project admin dashboard.
143143

144-
For details on custom domains, see our documentation on :doc:`/custom_domains`.
144+
For details on custom domains, see our documentation on :doc:`/custom-domains`.
145145

146146

147147
Where do I need to put my docs for RTD to find it?

0 commit comments

Comments
 (0)