diff --git a/docs/conf.py b/docs/conf.py index 8f58fdefe03..d8eff0a89f5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -157,7 +157,8 @@ hoverxref_domains = ["py"] hoverxref_roles = [ "option", - "doc", + "doc", # Documentation pages + "term", # Glossary terms ] hoverxref_role_types = { "mod": "modal", # for Python Sphinx Domain diff --git a/docs/user/canonical-urls.rst b/docs/user/canonical-urls.rst new file mode 100644 index 00000000000..b75071e8045 --- /dev/null +++ b/docs/user/canonical-urls.rst @@ -0,0 +1,71 @@ +Canonical URLs +============== + +A `canonical URL`_ +allows you to specify the preferred version of a web page to prevent duplicated content. +They are mainly used by search engines to link users to the correct +version and domain of your documentation. + +If canonical URL's aren't used, +it's easy for outdated documentation to be the top search result for various pages in your documentation. +This is not a perfect solution for this problem, +but generally people finding outdated documentation is a big problem, +and this is one of the suggested ways to solve it from search engines. + +.. _canonical URL: https://developers.google.com/search/docs/advanced/crawling/consolidate-duplicate-urls + +How Read the Docs generates canonical URLs +------------------------------------------ + +The canonical URL takes into account: + +* The default version of your project (usually "latest" or "stable"). +* The canonical :doc:`custom domain ` if you have one, + otherwise the default :ref:`subdomain ` will be used. + +For example, if you have a project named ``example-docs`` +with a custom domain ``https://docs.example.com``, +then your documentation will be served at ``https://example-docs.readthedocs.io`` and ``https://docs.example.com``. +Without specifying a canonical URL, a search engine like Google will index both domains. + +You'll want to use ``https://docs.example.com`` as your canonical domain. +This means that when Google indexes a page like ``https://example-docs.readthedocs.io/en/latest/``, +it will know that it should really point at ``https://docs.example.com/en/latest/``, +thus avoiding duplicating the content. + +.. note:: + + 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. + +Implementation +-------------- + +The canonical URL is set in HTML with a ``link`` element. +For example, this page has a canonical URL of: + +.. code-block:: html + + + +Sphinx +~~~~~~ + +If you are using :doc:`Sphinx `, +Read the Docs will set the value of the html_baseurl_ setting (if isn't already set) to your canonical domain. +If you already have ``html_baseurl`` set, you need to ensure that the value is correct. + +.. _html_baseurl: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_baseurl + +Mkdocs +~~~~~~ + +For :doc:`MkDocs ` this isn't done automatically, +but you can use the site_url_ setting to set a similar value. + +.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url + +.. warning:: + + If you change your default version or canonical domain, + you'll need to re-build all your versions in order to update their + canonical URL to the new one. diff --git a/docs/user/custom-domains.rst b/docs/user/custom-domains.rst new file mode 100644 index 00000000000..7e0ae6683c6 --- /dev/null +++ b/docs/user/custom-domains.rst @@ -0,0 +1,118 @@ +Custom Domains +============== + +Custom domains allow you to serve your documentation from your own domain. +This is great for maintaining a consistent brand for your documentation and application. + +By default, your documentation is served from a Read the Docs :ref:`subdomain ` using the project's :term:`slug`: + +* ``.readthedocs.io`` for |org_brand| +* ``.readthedocs-hosted.com`` for |com_brand|. + +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``. + +.. contents:: Contents + :local: + +Adding a custom domain +---------------------- + +To setup your custom domain, follow these steps: + +#. Go the :guilabel:`Admin` tab of your project. +#. Click on :guilabel:`Domains`. +#. Enter your domain. +#. Mark the :guilabel:`Canonical` option if you want use this domain + as your :doc:`canonical domain `. +#. Click on :guilabel:`Add`. +#. At the top of the next page you'll find the value of the DNS record that you need to point your domain to. + For |org_brand| this is ``readthedocs.io``, and for :doc:`/commercial/index` + the record is in the form of ``.domains.readthedocs.com``. + + .. note:: + + For a subdomain like ``docs.example.com`` add a CNAME record, + and for a root domain like ``example.com`` use an ANAME or ALIAS record. + +By default, we provide a validated SSL certificate for the domain, +managed by `Cloudflare `_. +The SSL certificate issuance should happen within a few minutes, +but might take up to one hour. +See `SSL certificate issue delays`_ for more troubleshooting options. + +As an example, our blog's DNS record looks like this: + +.. prompt:: bash $, auto + + $ dig +short CNAME blog.readthedocs.com + readthedocs.io. + +.. warning:: + + We don't support pointing subdomains or root domains to a project using A records. + DNS A records require a static IP address and our IPs may change without notice. + + +Removing a custom domain +------------------------ + +To remove a custom domain: + +#. Go the :guilabel:`Admin` tab of your project. +#. Click on :guilabel:`Domains`. +#. Click the :guilabel:`Remove` button next to the domain. +#. Click :guilabel:`Confirm` on the confirmation page. + +.. warning:: + + Once a domain is removed, + your previous documentation domain is no longer served by Read the Docs, + and any request for it will return a 404 Not Found! + +Strict Transport Security (HSTS) and other custom headers +--------------------------------------------------------- + +By default, we do not return a `Strict Transport Security header`_ (HSTS) for user custom domains. +This is a conscious decision as it can be misconfigured in a not easily reversible way. +For both |org_brand| and |com_brand|, HSTS and other custom headers can be set upon request. + +We always return the HSTS header with a max-age of at least one year +for our own domains including ``*.readthedocs.io``, ``*.readthedocs-hosted.com``, ``readthedocs.org`` and ``readthedocs.com``. + +Please contact :doc:`support` if you want to add a custom header to your domain. + +.. _Strict Transport Security header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security + +Multiple documentation sites as sub-folders of a domain +------------------------------------------------------- + +You may host multiple documentation repositories as **sub-folders of a single domain**. +For example, ``docs.example.org/projects/repo1`` and ``docs.example.org/projects/repo2``. +This is `a way to boost the SEO of your website `_. + +See :doc:`subprojects` for more information. + +Troubleshooting +--------------- + +SSL certificate issue delays +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The status of your domain validation and certificate can always be seen on the details page for your domain +under :guilabel:`Admin` > :guilabel:`Domains` > :guilabel:`YOURDOMAIN.TLD (details)`. + +Domains are usually validated and a certificate issued within minutes. +However, if you setup the domain in Read the Docs without provisioning the necessary DNS changes +and then update DNS hours or days later, +this can cause a delay in validating because there is an exponential back-off in validation. + +.. tip:: + + Loading the domain details in the Read the Docs dashboard and saving the domain again will force a revalidation. + +Migrating from GitBook +~~~~~~~~~~~~~~~~~~~~~~ + +If your custom domain was previously used in GitBook, contact GitBook support (via live chat in their website) +to remove the domain name from their DNS Zone in order for your domain name to work with Read the Docs, +else it will always redirect to GitBook. diff --git a/docs/user/custom_domains.rst b/docs/user/custom_domains.rst deleted file mode 100644 index 83ba73fea0f..00000000000 --- a/docs/user/custom_domains.rst +++ /dev/null @@ -1,197 +0,0 @@ -Custom Domains and White Labeling -================================= - -Once a project is imported into Read the Docs, -by default it's hosted under a subdomain on one of our domains. -If you need a custom domain, see :ref:`custom_domains:custom domain support`. - -Subdomain support ------------------ - -Every project has a subdomain that is available to serve its documentation. -If you go to ``.readthedocs.io``, it should show you the latest version of your documentation. -A good example is https://pip.readthedocs.io -For :doc:`/commercial/index` the subdomain looks like ``.readthedocs-hosted.com``. - -Custom domain support ---------------------- - -You can also host your documentation from your own domain. - -.. note:: - - We don't currently support pointing subdomains or root domains to a project using A records. - DNS A records require a static IP address and our IPs may change without notice. - -.. tabs:: - - .. tab:: Read the Docs Community - - In order to setup your custom domain, follow these steps: - - #. For a subdomain like ``docs.example.com``, add a CNAME record in your DNS that points the domain to ``readthedocs.io``. - For a root domain like ``example.com`` use an ANAME or ALIAS record pointing to ``readthedocs.io``. - #. Go the :guilabel:`Admin` tab of your project - #. Click on :guilabel:`Domains` - #. Enter your domain and click on :guilabel:`Add` - - By default, we provide a validated SSL certificate for the domain. - This service is generously provided by Cloudflare. - The SSL certificate issuance can take about one hour, - you can see the status of the certificate on the domain page in your project. - - As an example, fabric's DNS record looks like this: - - .. prompt:: bash $, auto - - $ dig CNAME +short docs.fabfile.org - readthedocs.io. - - .. tab:: Read the Docs for Business - - In order to setup your custom domain, follow these steps: - - #. Go the :guilabel:`Admin` tab of your project - #. Click on :guilabel:`Domains` - #. Enter your domain and click on :guilabel:`Add` - #. Follow the steps shown on the domain page. - This will require adding 2 DNS records, one pointing your custom domain to our servers, - and another allowing us to provision an SSL certificate. - - By default, we provide a validated SSL certificate for the domain. - The SSL certificate issuance can take a few days, - you can see the status of the certificate on the domain page in your project. - - .. note:: - - Some older setups configured a CNAME record pointing to ``.users.readthedocs.com``. - These domains will continue to resolve. - - .. note:: - - You will need to keep the extra DNS records after the setup is complete. - If you remove the verification record, the certificate won't renew automatically, - and if you remove the CNAME pointing to us, your domain won't serve the documentation. - -Strict Transport Security -+++++++++++++++++++++++++ - -By default, we do not return a `Strict Transport Security header`_ (HSTS) for user custom domains. -This is a conscious decision as it can be misconfigured in a not easily reversible way. -For both |org_brand| and |com_brand|, HSTS for custom domains can be set upon request. - -We always return the HSTS header with a max-age of at least one year -for our own domains including ``*.readthedocs.io``, ``*.readthedocs-hosted.com``, ``readthedocs.org`` and ``readthedocs.com``. - -.. _Strict Transport Security header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security - -Multiple documentation sites as sub-folders of a domain -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -You may host multiple documentation repositories as **sub-folders of a single domain**. -For example, ``docs.example.org/projects/repo1`` and ``docs.example.org/projects/repo2``. -This is `a way to boost the SEO of your website `_. - -See :doc:`subprojects` for more information. - -Troubleshooting -+++++++++++++++ - -SSL certificate issue delays -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The status of your domain validation and certificate can always be seen on the details page for your domain -under :guilabel:`Admin` > :guilabel:`Domains` > :guilabel:`YOURDOMAIN.TLD (details)`. - -* For |org_brand|, domains are usually validated and a certificate issued within minutes. - However, if you setup the domain in Read the Docs without provisioning the necessary DNS changes - and then update DNS hours or days later, - this can cause a delay in validating because there is an exponential back-off in validation. - Loading the domain details in the Read the Docs dashboard and saving the domain again will force a revalidation. -* For |com_brand|, domains can take up to a couple days to validate and issue a certificate. - To avoid any downtime in moving a domain from somewhere else to Read the Docs, - it is possible to validate the domain and provision the certificate before pointing your domain to Read the Docs. - -Certificate authority authorization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Certificate authority authorization (CAA) is a security feature that allows domain owners to limit -which certificate authorities (CAs) can issue certificates for a domain. -This is done by setting CAA DNS records for your domain. -CAA records are typically on the root domain, not subdomains -since you can't have a CNAME and CAA record for the same subdomain. -Here's an example for palletsprojects.com: - -.. prompt:: bash $, auto - - $ dig CAA +short palletsprojects.com - 0 issue "digicert.com" - 0 issue "comodoca.com" - 0 issue "letsencrypt.org" - -If there are CAA records for your domain that do not allow the certificate authorities that Read the Docs uses, -you may see an error message like ``pending_validation: caa_error: YOURDOMAIN.TLD`` -in the Read the Docs dashboard for your domain. -You will need to update your CAA records to allow us to issue the certificate. - -* For |org_brand|, we use Cloudflare which uses Digicert as a CA. See the `Cloudflare CAA FAQ`_ for details. -* For |com_brand|, we use AWS Certificate Manager as a CA. See the `Amazon CAA guide`_ for details. - -.. _Cloudflare CAA FAQ: https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ -.. _Amazon CAA guide: https://docs.aws.amazon.com/acm/latest/userguide/setup-caa.html - -.. note:: - - If your custom domain was previously used in GitBook, contact GitBook support (via live chat in their website) - to remove the domain name from their DNS Zone in order for your domain name to work with Read the Docs, - else it will always redirect to GitBook. - -Canonical URLs --------------- - -Canonical URLs allow people to have consistent page URLs for domains. -This is mainly useful for search engines, -so that they can send people to the correct page. - -Read the Docs uses these in two ways: - -* We point all versions of your docs at default version, usually "latest" or "stable", as canonical. -* We point at the user specified canonical URL, generally a custom domain for your docs. - -Example -+++++++ - -Fabric hosts their docs on Read the Docs. -They mostly use their own domain for them ``http://docs.fabfile.org``. -This means that Google will index both ``http://fabric-docs.readthedocs.io`` and -``http://docs.fabfile.org`` for their documentation. - -Fabric will want to set ``http://docs.fabfile.org`` as their canonical URL. -This means that when Google indexes ``http://fabric-docs.readthedocs.io``, -it will know that it should really point at ``http://docs.fabfile.org``. - -Enabling -++++++++ - -You can set the canonical URL for your project in the Project Admin page. -Check your :guilabel:`Admin` > :guilabel:`Domains` page for the domains that we know about. - -Implementation -++++++++++++++ - -If you are using :doc:`Sphinx `, -Read the Docs will set the value of the html_baseurl_ setting (if isn't already set) to your canonical domain. - -.. _html_baseurl: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_baseurl - -If you are using :doc:`MkDocs `, -you can use the site_url_ setting. - -.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url - -If you look at the source code for documentation built after you set your canonical URL, -you should see a bit of HTML like this: - -.. code-block:: html - - diff --git a/docs/user/faq.rst b/docs/user/faq.rst index de58da78331..999fe10647b 100644 --- a/docs/user/faq.rst +++ b/docs/user/faq.rst @@ -141,7 +141,7 @@ http://docs..org/projects/kombu/en/latest/ You can add subprojects in the project admin dashboard. -For details on custom domains, see our documentation on :doc:`/custom_domains`. +For details on custom domains, see our documentation on :doc:`/custom-domains`. Where do I need to put my docs for RTD to find it? diff --git a/docs/user/features.rst b/docs/user/features.rst index f63822d4f24..d443d76d5c0 100644 --- a/docs/user/features.rst +++ b/docs/user/features.rst @@ -26,7 +26,7 @@ we assign you a URL based on your project name. You are welcome to use this URL, but we also fully support custom domains for all our documentation projects. -Learn more about :doc:`/custom_domains`. +Learn more about :doc:`/custom-domains`. Versioned Documentation ----------------------- diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index b0dab24d0a7..fe071bd2c1b 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -25,6 +25,9 @@ Glossary project page Another name for :term:`project home`. + slug + The lower case & hyphenated name of your project that is used in URL's. You can find this on the project :guilabel:`Overview` section of your documentation under ``Project Slug``. + root URL Home URL of your documentation without the ``/`` and ``/`` segments. For projects without custom domains, the one ending in ``.readthedocs.io/`` diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst index 1a291f7436e..08542aed8b0 100644 --- a/docs/user/guides/technical-docs-seo-guide.rst +++ b/docs/user/guides/technical-docs-seo-guide.rst @@ -161,8 +161,8 @@ The canonical URL tells search engines where the original version your documentation is even if you have multiple versions on the internet (for example, incomplete translations or deprecated versions). -Read the Docs supports :ref:`setting the canonical URL ` -if you are using a :doc:`custom domain ` +Read the Docs supports :doc:`setting the canonical URL ` +if you are using a :doc:`custom domain ` under :guilabel:`Admin` > :guilabel:`Domains` in the Read the Docs dashboard. diff --git a/docs/user/hosting.rst b/docs/user/hosting.rst index d05235d6a13..c37aa89ea07 100644 --- a/docs/user/hosting.rst +++ b/docs/user/hosting.rst @@ -8,6 +8,16 @@ We support a number of important features that you would expect for a documentat :local: :depth: 1 +Subdomain support +----------------- + +Every project has a subdomain that is available to serve its documentation based on it's :term:`slug`. +If you go to ``.readthedocs.io``, it should show you the latest version of your documentation, +for example https://docs.readthedocs.io. +For :doc:`/commercial/index` the subdomain looks like ``.readthedocs-hosted.com``. + +.. seealso:: :doc:`/custom-domains`. + Content Delivery Network (CDN) ------------------------------ diff --git a/docs/user/index.rst b/docs/user/index.rst index 3d4937bc275..d74846a327e 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -76,7 +76,7 @@ and some of the core features of Read the Docs. * **Overview of core features**: :doc:`/integrations` | - :doc:`/custom_domains` | + :doc:`/custom-domains` | :doc:`/versions` | :doc:`/downloadable-documentation` | :doc:`/hosting` | @@ -108,7 +108,7 @@ and some of the core features of Read the Docs. /config-file/index /integrations - /custom_domains + /custom-domains /versions /downloadable-documentation /hosting @@ -209,6 +209,7 @@ out of your documentation and Read the Docs. automatic-redirects automation-rules + canonical-urls api/index