Merge canonical urls content into custom domains documentation

Author: astrojuanlu

docs/canonical.rst

@@ -132,3 +132,53 @@ You will need to update your CAA records to allow us to issue the certificate.
    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 the "latest" version 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 </intro/getting-started-with-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 </intro/getting-started-with-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
+
+    <link rel="canonical" href="http://docs.fabfile.org/en/2.4/" />

docs/custom_domains.rst

@@ -161,7 +161,7 @@ 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 :doc:`setting the canonical URL </canonical>`
+Read the Docs supports :ref:`setting the canonical URL <custom_domains:Canonical URLs>`
 if you are using a :doc:`custom domain </custom_domains>`
 under :guilabel:`Admin` > :guilabel:`Domains`
 in the Read the Docs dashboard.

docs/guides/technical-docs-seo-guide.rst

@@ -77,7 +77,6 @@ and some of the core features of Read the Docs.
 * **Overview of core features**:
   :doc:`Incoming webhooks </webhooks>` |
   :doc:`/custom_domains` |
-  :doc:`/canonical` |
   :doc:`/versions` |
   :doc:`/downloadable-documentation` |
   :doc:`/hosting` |
@@ -110,7 +109,6 @@ and some of the core features of Read the Docs.
    /config-file/index
    /webhooks
    /custom_domains
-   /canonical
    /versions
    /downloadable-documentation
    /hosting

docs/index.rst

@@ -23,6 +23,6 @@ if pip was set as a "Single Version" project, then links to its documentation wo
 ``http://pip.readthedocs.io/`` rather than the default ``http://pip.readthedocs.io/en/latest/``.
 
 Documentation at ``/<language>/<default_version>/`` will still be served for backwards compatibility reasons.
-However, our usage of :doc:`canonical` should stop these from being indexed by Google.
+However, our usage of :ref:`custom_domains:Canonical URLs` should stop these from being indexed by Google.
 
 .. _dashboard: https://readthedocs.org/dashboard/