diff --git a/docs/conf.py b/docs/conf.py index c85f38f1281..3e91141d6b4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,6 +32,7 @@ "multiproject", "sphinx.ext.autosectionlabel", "sphinx.ext.autodoc", + "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinxcontrib.httpdomain", "sphinxcontrib.video", @@ -159,8 +160,11 @@ hoverxref_domains = ["py"] hoverxref_roles = [ "option", - "doc", # Documentation pages - "term", # Glossary terms + # Documentation pages + # Not supported yet: https://github.com/readthedocs/sphinx-hoverxref/issues/18 + "doc", + # Glossary terms + "term", ] hoverxref_role_types = { "mod": "modal", # for Python Sphinx Domain @@ -206,3 +210,7 @@ # This page is under login r"https://readthedocs\.org/accounts/gold", ] + +extlinks = { + "rtd-issue": ("https://github.com/readthedocs/readthedocs.org/issues/%s", "#"), +} diff --git a/docs/user/canonical-urls.rst b/docs/user/canonical-urls.rst index b75071e8045..4a0a5156887 100644 --- a/docs/user/canonical-urls.rst +++ b/docs/user/canonical-urls.rst @@ -3,10 +3,13 @@ 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. +Here are some examples of when a canonical URL is used: -If canonical URL's aren't used, +- Search engines use your canonical URL to link users to the correct version and domain of your documentation. +- Many popular chat clients and social media networks generate link previews, + using your canonical URL as the final destination. + +If canonical URLs 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, @@ -14,10 +17,20 @@ 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 +.. tip:: + + In most cases, Read the Docs will automatically generate a canonical URL for Sphinx projects. + Most Sphinx users do not need to take further action. + +.. seealso:: + + :doc:`/guides/canonical-urls` + More information on how to enable canonical URLs in your project. + How Read the Docs generates canonical URLs ------------------------------------------ -The canonical URL takes into account: +The canonical URL takes the following into account: * The default version of your project (usually "latest" or "stable"). * The canonical :doc:`custom domain ` if you have one, @@ -40,32 +53,10 @@ thus avoiding duplicating the content. Implementation -------------- -The canonical URL is set in HTML with a ``link`` element. -For example, this page has a canonical URL of: +A canonical URL is automatically specified in the HTML output with a ```` element. +For instance, regardless of whether you are viewing this page on ``/en/latest`` or ``/en/stable``, +the following HTML header data will be present: .. 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 index b9bd1e6f6fc..259a1b3ac3b 100644 --- a/docs/user/custom-domains.rst +++ b/docs/user/custom-domains.rst @@ -1,126 +1,101 @@ 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. +You can serve your documentation project from your own domain, +for instance ``docs.example.com``. +This is great for maintaining a consistent brand for your product and its documentation. -By default, your documentation is served from a Read the Docs :ref:`subdomain ` using the project's :term:`slug`: +*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``. +.. seealso:: -.. contents:: Contents - :local: + :doc:`/guides/custom-domains` + Information on creating and managing custom domains, + and common configurations you might use to set up your domain -Adding a custom domain ----------------------- +How custom domains work +----------------------- -To setup your custom domain, follow these steps: +To use a custom domain, two actions are needed from you: -#. Go the :guilabel:`Admin` tab of your project. -#. Click on :guilabel:`Domains`. -#. Enter the domain where you want to serve the documentation from (e.g. ``docs.example.com``). -#. 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``. +#. Enter the domain in your Read the Docs project's :guilabel:`Admin` +#. Update your DNS provider with a new DNS entry. The name and value of the DNS entry is found in Read the Docs' :guilabel:`Admin`. - .. note:: +Once the new DNS record has propagated, +Read the Docs automatically issues an SSL certificate through Cloudflare and starts serving your documentation. - 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. +.. image:: img/mermaid-custom-domains.png + :alt: Diagram of the process of adding a custom domain on Read the Docs -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. +.. + We have generated an PNG version of the following diagram using mermaid.live + Firstly, we generate an SVG, then we render it in a browser, then we take a screenshot, + then we paste it into GIMP or similar and make the background transparent. -As an example, our blog's DNS record looks like this: + If you wish to sketch diagrams locally, you can add sphinxcontrib-mermaid to + this project's extensions and keep using the below code. -.. prompt:: bash $, auto + SVG does not work because it embeds fontawesome from CDN (which is blocked by CSP) - $ dig +short CNAME blog.readthedocs.com - readthedocs.io. + PLEASE KEEP THIS SOURCE CODE UPDATED + .. mermaid:: -.. warning:: + graph TD + subgraph rtd [On Read the Docs] + A(fa:fa-pencil Add docs.example.com as Custom Domain) + end + subgraph dns [On your domain's DNS administration] + B(fa:fa-pencil Edit/add a DNS entry for docs.example.com
making it point to Read the Docs) + end - 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. + rtd & dns-->C(fa:fa-spinner Wait for DNS propagation.
Usually just a few minutes) + direction LR + subgraph automatic [fa:fa-paper-plane The rest is handled automatically] + direction TB + D(fa:fa-spinner The next time your project is built,
its Canonical URLs use docs.example.com) + D-->E(Visit https://docs.example.com) + E-->F(fa:fa-lock Correct SSL Certificate
automatically used) + F-->G(fa:fa-check Read the Docs knows
to serve your project
at docs.example.com) + end -Removing a custom domain ------------------------- + C-->automatic -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. +Your documentation can have multiple secondary domains but only one **canonical** domain name. +Additional domains or subdomains will redirect to the canonical domain. -.. warning:: +To make this work, Read the Docs generates a special text that you are responsible for copy-pasting to your domain's DNS. +In most cases, the ``CNAME`` record is used. +This is all that's needed for a web browser to resolve your domain name to Read the Docs' servers and for our servers to match the right documentation project. +You can find step-by-step instructions for this in :doc:`/guides/custom-domains`. - 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! +Read the Docs uses a :ref:`hosting:Content Delivery Network (CDN)` to host and serve your documentation pages. +This final step isn't changed by a custom domain +and therefore the response times are unaffected as the delivery of resources happens through the same CDN setup. -Strict Transport Security (HSTS) and other custom headers ---------------------------------------------------------- +Considerations for custom domain usage +-------------------------------------- -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. +Some open source projects have seen their domains expire. +Even prominent ones. +**It's important that you give the responsibility for managing your domain to someone reliable in your organization.** -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``. +The **canonical domain** feature allows you to have several domains and the canonical domain will be indexed by search engines. +The domain that you choose as your canonical domain is by far the most important one. +If you lose the canonical domain, +someone else can set up a website that search results will end up referring to. -Please contact :doc:`support` if you want to add a custom header to your domain. +.. seealso:: -.. _Strict Transport Security header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security + In a URL, both the domain and the path (``https:///``) are important. + In combination, they are referred to as the *canonical URL* of a resource. -Multiple documentation sites as sub-folders of a domain -------------------------------------------------------- + Most documentation projects are versioned. + Therefore, it's important to ensure that incoming links and search engine results point to the canonical URL of the resource + and not a specific version that becomes outdated. -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. - -The validation process period has ended -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After you add a new custom domain, you have 30 days to complete the configuration. -Once that period has ended, we will stop trying to validate your domain. -If you still want to complete the configuration, -go to your domain and click on :guilabel:`Save` to restart the process. - -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. + To learn more about canonical URLs, see: :doc:`/canonical-urls` diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index a2b83cca532..d022eeb4f41 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -31,6 +31,12 @@ Glossary and hypens. You can retreive your project or version slugs from :doc:`our API `. + subproject + Project A can be configured such that when requesting a URL ``/projects/``, + the root of project B is returned. + In this case, *project B* is the subproject. + Read more in :doc:`/subprojects`. + 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/administrators.rst b/docs/user/guides/administrators.rst index eca54090f06..1afabab5c51 100644 --- a/docs/user/guides/administrators.rst +++ b/docs/user/guides/administrators.rst @@ -12,6 +12,8 @@ have a look at our :doc:`/tutorial/index`. .. toctree:: :maxdepth: 1 + Manage Custom Domains + Enable Canonical URLs technical-docs-seo-guide manage-translations-sphinx hiding-a-version diff --git a/docs/user/guides/canonical-urls.rst b/docs/user/guides/canonical-urls.rst new file mode 100644 index 00000000000..7fc3d1e976b --- /dev/null +++ b/docs/user/guides/canonical-urls.rst @@ -0,0 +1,58 @@ +How to Enable Canonical URLs +============================ + +In this guide, we introduce relevant settings for enabling canonical URLs in popular documentation frameworks. + +If you need to customize the domain from which your documentation project is served, +please refer to :doc:`/guides/custom-domains`. + +Sphinx +~~~~~~ + +If you are using :doc:`Sphinx `, +Read the Docs will automatically add a default value of the html_baseurl_ setting matching your canonical domain. + +If you are using a custom ``html_baseurl`` in your ``conf.py``, +you have to ensure that the value is correct. +This can be complex, +supporting pull request builds (which are published on a separate domain), +special branches +or if you are using :term:`subproject` s or :ref:`translations `. +We recommend not including a ``html_baseurl`` in your ``conf.py``, +and letting Read the Docs define it. + +.. _html_baseurl: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_baseurl + +MkDocs +~~~~~~ + +For :doc:`MkDocs ` we do not define your canonical domain automatically, +but you can use the site_url_ setting to set a similar value. + +In your ``mkdocs.yml``, define the following: + +.. code-block:: yaml + + # Canonical URL, adjust as need with respect to your slug, language, + # default branch and if you use a custom domain. + site_url: https://.readthedocs.io/en/stable/ + +Note that this will define the same canonical URL for all your branches and versions. +According to MkDocs, defining site_url_ will only define the canonical URL of a website and does not affect the base URL of generated links, CSS, or Javascript files. + +.. note:: + + 2 known issues are currently making it impossible to use `environment variables in MkDocs configuration`_. + Once these issues are solved, it will be easier. + + - Support for ``!ENV``: :rtd-issue:`8529` + - Add environment variable for canonical URL: :rtd-issue:`9781` + +.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url +.. _environment variables in MkDocs configuration: https://www.mkdocs.org/user-guide/configuration/#environment-variables + +.. 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/guides/custom-domains.rst b/docs/user/guides/custom-domains.rst new file mode 100644 index 00000000000..9c9961f37fd --- /dev/null +++ b/docs/user/guides/custom-domains.rst @@ -0,0 +1,128 @@ +How To Manage Custom Domains +============================ + +This guide describes how to host your documentation using your own domain name, such as ``docs.example.com``. + +.. contents:: Contents + :local: + +Adding a custom domain +---------------------- + +To setup your :doc:`custom domain `, follow these steps: + +#. Go the :guilabel:`Admin` tab of your project. +#. Click on :guilabel:`Domains`. +#. Enter the domain where you want to serve the documentation from (e.g. ``docs.example.com``). +#. 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``. + + +**Once you have completed these steps and your new DNS entry has propagated (usually takes a few minutes), you need to build your project's published branches again so the Canonical URL is correct.** + + .. 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. + +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. + +To see if your DNS change has propagated, you can use a tool like ``dig`` to inspect your domain from your command line. +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``. + +.. note:: + + 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 `_. + +.. seealso:: + + :doc:`/subprojects` + Further information about hosting multiple documentation repositories, using the :term:`subproject` feature. + + +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. + +The validation process period has ended +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you add a new custom domain, you have 30 days to complete the configuration. +Once that period has ended, we will stop trying to validate your domain. +If you still want to complete the configuration, +go to your domain and click on :guilabel:`Save` to restart the process. + +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, +otherwise it will always redirect to GitBook. diff --git a/docs/user/hosting.rst b/docs/user/hosting.rst index c37aa89ea07..355b0ea8737 100644 --- a/docs/user/hosting.rst +++ b/docs/user/hosting.rst @@ -16,7 +16,10 @@ If you go to ``.readthedocs.io``, it should show you the latest version of for example https://docs.readthedocs.io. For :doc:`/commercial/index` the subdomain looks like ``.readthedocs-hosted.com``. -.. seealso:: :doc:`/custom-domains`. +.. seealso:: + + :doc:`/custom-domains` + More information on using a custom domain. Content Delivery Network (CDN) ------------------------------ @@ -25,8 +28,7 @@ A CDN is used for making documentation pages faster for your users. This is done by caching the documentation page content in multiple data centers around the world, and then serving docs from the data center closest to the user. -We support CDN's on both of our sites, -as we talk about below. +We support CDNs on both of our sites: .. tabs:: @@ -34,7 +36,7 @@ as we talk about below. On |org_brand|, we are able to provide a CDN to all the projects that we host. - This service is graciously sponsored by `CloudFlare`_. + This service is graciously sponsored by `Cloudflare`_. We bust the cache on the CDN when the following actions happen: @@ -49,7 +51,13 @@ as we talk about below. we offer a CDN as part of our **Pro plan** and above. Please contact support@readthedocs.com to discuss how we can enable this for you. -.. _CloudFlare: https://www.cloudflare.com/ + We invalidate and refresh the cache on the CDN when the following actions happen: + + * Your project is saved + * Your domain is saved + * A version or branch is built + +.. _Cloudflare: https://www.cloudflare.com/ Sitemaps -------- diff --git a/docs/user/img/mermaid-custom-domains.png b/docs/user/img/mermaid-custom-domains.png new file mode 100644 index 00000000000..0dc491d38ab Binary files /dev/null and b/docs/user/img/mermaid-custom-domains.png differ diff --git a/docs/user/img/mermaid-custom-domains.svg b/docs/user/img/mermaid-custom-domains.svg new file mode 100644 index 00000000000..2b0ccc6dce1 --- /dev/null +++ b/docs/user/img/mermaid-custom-domains.svg @@ -0,0 +1 @@ +
The rest is handled automatically
The next time your project is built,
its Canonical URLs use docs.example.com
Visit https://docs.example.com
Correct SSL Certificate
automatically used
Read the Docs knows
to serve your project
at docs.example.com
On your domain's DNS administration
Edit/add a DNS entry for docs.example.com
making it point to Read the Docs
On Read the Docs
Add docs.example.com as Custom Domain
Wait for DNS propagation.
Usually just a few minutes
 diff --git a/docs/user/index.rst b/docs/user/index.rst index 747067e820f..2c784ebe7c4 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -77,6 +77,7 @@ to help you create fantastic documentation for your project. :caption: Explanation /build-notifications + /custom-domains /downloadable-documentation @@ -144,7 +145,6 @@ and some of the core features of Read the Docs. /features /config-file/index /integrations - /custom-domains /versions /hosting /server-side-search/index @@ -178,6 +178,7 @@ and how to write successful documentation. :doc:`More guides for authors ` * **For project administrators**: + :doc:`Manage Custom Domains ` | :doc:`/guides/technical-docs-seo-guide` | :doc:`/guides/manage-translations-sphinx` | :doc:`/guides/private-submodules` | diff --git a/requirements/docs.in b/requirements/docs.in index c2bdbfb0941..441a07ab423 100644 --- a/requirements/docs.in +++ b/requirements/docs.in @@ -15,6 +15,7 @@ git+https://github.com/readthedocs/sphinx-hoverxref # Docs sphinxemoji==0.2.0 sphinxcontrib-httpdomain==1.8.0 +sphinxcontrib-mermaid>=0.7.1,<0.8 sphinx-prompt==1.4.0 sphinx-notfound-page==0.8 sphinx-autobuild==2021.3.14 diff --git a/requirements/docs.txt b/requirements/docs.txt index 52d9616a075..c43d05412d2 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -2,7 +2,7 @@ # This file is autogenerated by pip-compile with Python 3.10 # by the following command: # -# pip-compile --output-file=requirements/docs.txt requirements/docs.in +# pip-compile requirements/docs.in # alabaster==0.7.12 # via @@ -405,6 +405,8 @@ sphinxcontrib-jsmath==1.0.1 # via # -r requirements/pip.txt # sphinx +sphinxcontrib-mermaid==0.7.1 + # via -r requirements/docs.in sphinxcontrib-qthelp==1.0.3 # via # -r requirements/pip.txt