readthedocs · astrojuanlu · Sep 28, 2021 · Sep 27, 2021 · Sep 27, 2021 · Sep 27, 2021
diff --git a/docs/advertising/advertising-details.rst b/docs/advertising/advertising-details.rst
@@ -119,13 +119,13 @@ our own goals.
 
 We have taken steps to address some of the privacy concerns surrounding GA.
 These steps apply both to analytics collected by Read the Docs and when
-:doc:`authors enable analytics on their docs </google-analytics>`.
+:ref:`authors enable analytics on their docs <analytics:Enabling Google Analytics on your Project>`.
 
 * Users can opt-out of analytics by using the Do Not Track feature of their browser.
 * Read the Docs instructs Google to anonymize IP addresses sent to them.
 * The cookies set by GA expire in 30 days rather than the default 2 years.
 * Project maintainers can completely disable analytics on their own projects.
-  Follow the steps in :ref:`google-analytics:Disabling Google Analytics on your project`.
+  Follow the steps in :ref:`analytics:Disabling Google Analytics on your project`.
 
 
 Why we use analytics

diff --git a/docs/analytics.rst b/docs/analytics.rst
@@ -1,7 +1,7 @@
-Analytics
----------
+Traffic Analytics
-Traffic Analytics
+Traffic Analytics - See top performing doc pages
-Traffic Analytics
+Traffic Analytics - See top performing doc pages
+=================
 
-Analytics lets you see *which* documents your users are reading.
+Traffic Analytics lets you see *which* documents your users are reading.
 This allows you to understand how your documentation is being used,
 so you can focus on expanding and updating parts people are reading most.
 
@@ -18,7 +18,36 @@ and then click on :guilabel:`Traffic Analytics`.
 
 You can also access to analytics data from :ref:`search results <server-side-search:analytics>`.
 
+Enabling Google Analytics on your Project
+-----------------------------------------
+
+Read the Docs has native support for Google Analytics.
+You can enable it by:
+
+* Going to :guilabel:`Admin` > :guilabel:`Advanced Settings` in your project.
+* Fill in the **Analytics code** heading with your Google Tracking ID (example `UA-123456674-1`)
+
+Once your documentation rebuilds it will include your Analytics tracking code and start sending data.
+Google Analytics usually takes 60 minutes,
+and sometimes can take up to a day before it starts reporting data.
+
 .. note::
 
-   If you require more information about page views,
-   you can use a solution like :doc:`Google Analytics </google-analytics>`.
+   Read the Docs takes some extra precautions with analytics to protect user privacy.
+   As a result, users with Do Not Track enabled will not be counted
+   for the purpose of analytics.
+
+   For more details, see the
+   :ref:`Do Not Track section <privacy-policy:Do Not Track>`
+   of our privacy policy.
+
+Disabling Google Analytics on your project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Google Analytics can be completely disabled on your own projects.
+To disable Google Analytics:
+
+* Going to :guilabel:`Admin` > :guilabel:`Advanced Settings` in your project.
+* Check the box **Disable Analytics**.
+
+Your documentation will need to be rebuilt for this change to take effect.
diff --git a/docs/canonical.rst b/docs/canonical.rst
diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst
@@ -133,41 +133,52 @@ You will need to update your CAA records to allow us to issue the certificate.
    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.
 
-Proxy SSL
----------
-
-.. warning::
-
-   This option is deprecated,
-   we already issue SSL certificates for all domains.
-
-If you would prefer to do your own SSL termination
-on a server you own and control,
-you can do that although the setup is a bit more complex.
-
-Broadly, the steps are:
-
-* Have a server listening on 443 that you control
-* Procure an SSL certificate for your domain and provision it
-  and the private key on your server.
-* Add a domain that you wish to point at Read the Docs
-* Enable proxying to us, with a custom ``X-RTD-SLUG`` header
-
-An example nginx configuration for pip would look like:
-
-.. code-block:: nginx
-   :emphasize-lines: 9
-
-    server {
-        server_name pip.pypa.io;
-        location / {
-            proxy_pass https://pip.readthedocs.io:443;
-            proxy_set_header Host $http_host;
-            proxy_set_header X-Forwarded-Proto https;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Scheme $scheme;
-            proxy_set_header X-RTD-SLUG pip;
-            proxy_connect_timeout 10s;
-            proxy_read_timeout 20s;
-        }
-    }
+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/" />
diff --git a/docs/features.rst b/docs/features.rst
@@ -71,7 +71,7 @@ We offer a number of search features:
 * Search across :doc:`subprojects </subprojects>`
 * Search results land on the exact content you were looking for
 * Search across projects you have access to (available on |com_brand|)
-* A full range of :doc:`search operators </guides/searching-with-readthedocs>` including exact matching and excluding phrases.
+* A full range of :doc:`search operators </guides/advanced-search>` including exact matching and excluding phrases.
 
 Learn more about :doc:`/server-side-search`.
 

diff --git a/docs/google-analytics.rst b/docs/google-analytics.rst
diff --git a/docs/guides/administrators.rst b/docs/guides/administrators.rst
@@ -3,7 +3,7 @@ Guides for project administrators
 
 These guides cover common use cases
 relevant for managing documentation projects,
-using the Read the Docs web interface
+using the Read the Docs web interface,
 and making changes to the configuration files.
 
 For an introduction to Read the Docs,
@@ -13,8 +13,8 @@ have a look at our :doc:`/tutorial/index`.
    :maxdepth: 1
 
    technical-docs-seo-guide
-   manage-translations
-   searching-with-readthedocs
+   manage-translations-sphinx
+   advanced-search
    hiding-a-version
    deprecating-content
    pdf-non-ascii-languages

diff --git a/docs/guides/searching-with-readthedocs.rst → docs/guides/advanced-search.rst b/docs/guides/searching-with-readthedocs.rst → docs/guides/advanced-search.rst
@@ -1,5 +1,5 @@
-Searching with Read the Docs
-============================
+Using advanced search features
+==============================
 
 Read the Docs uses :doc:`/server-side-search` to power our search.
 This guide explains how to add a "search as you type" feature to your documentation,

diff --git a/docs/guides/deprecating-content.rst b/docs/guides/deprecating-content.rst
@@ -1,5 +1,5 @@
-Deprecating Content on Read the Docs
-====================================
+Deprecating Content
+===================
 
 When you deprecate a feature from your project,
 you may want to deprecate its docs as well,
@@ -40,8 +40,8 @@ and mark the :guilabel:`Hidden` option. Check :ref:`versions:Version States` for
 
    .. _semver: https://semver.org/
 
-Deprecating content
--------------------
+Deprecating pages
+-----------------
 
 You may not always want to deprecate a version, but deprecate some pages.
 For example, if you have documentation about two APIs and you want to deprecate v1:

diff --git a/docs/guides/manage-translations.rst → docs/guides/manage-translations-sphinx.rst b/docs/guides/manage-translations.rst → docs/guides/manage-translations-sphinx.rst
@@ -1,5 +1,5 @@
-Manage Translations
-===================
+Manage Translations for Sphinx projects
+=======================================
 
 This guide walks through the process needed to manage translations of your documentation.
 Once this work is done, you can setup your project under Read the Docs to build each language of your documentation by reading :doc:`/localization`.

diff --git a/docs/guides/technical-docs-seo-guide.rst b/docs/guides/technical-docs-seo-guide.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.
@@ -266,7 +266,7 @@ Some of the most valuable feedback these provide include:
 Analytics tools
 ~~~~~~~~~~~~~~~
 
-A tool like :doc:`Google Analytics </google-analytics>`
+A tool like :ref:`Google Analytics <analytics:Enabling Google Analytics on your Project>`
 can give you feedback about the search terms people use to find your docs,
 your most popular pages, and lots of other useful data.