Docs: update custom domains docs #9266

stsewd · 2022-05-24T22:01:31Z

Changes:

Rename the page from custom_domains.rst -> custom-domain.rst (I'll create a redirect when this is approved)
Describe canonical urls in their own page (since they work even if you don't add a custom domain)
The creation of a custom domain for .com and .org are almost the same, so no more tabs
I have updated the FAQ about CAA records to mention that we already set the correct ones
Describe default subdomains on the hosting.rst page.\
Removed the part of title about "white labeling", there isn't any content about that in that page, and if any we should just add another page about it.

stsewd · 2022-05-25T18:43:56Z

docs/user/custom-domains.rst

+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 <https://moz.com/blog/subdomains-vs-subfolders-rel-canonical-vs-301-how-to-structure-links-optimally-for-seo-whiteboard-friday>`_.
+
+See :doc:`subprojects` for more information.


I think this doesn't make much sense to be here, but I don't know where else to put it, maybe we should put this on the features pages as the description for subprojects?

humitos · 2022-05-26T15:08:22Z

Rename the page from custom_domains.rst -> custom-domain.rst (I'll create a redirect when this is approved)

I think this change makes the review very hard because it's not detected as a rename and there is no diff see the changes. Is it possible to do this in a different commit?

agjohnson · 2022-05-26T17:25:46Z

I also prefer to isolate changes like this in individual commits -- moving files, linting, etc

stsewd · 2022-05-26T21:21:40Z

This has two commits now

humitos

This upgrade is great! We are mentioning all the news regarding custom domains and cleaning up the docs.

I think this PR does a great job on the technical side, but may not be too aligned with the marketing/narrative content we wanted to add to these feature pages. Is this going to be done in a different PR?

That said, I left some comments/suggestions to make some sections clearer from a user's perspective.

docs/user/custom-domains.rst

docs/user/canonical-urls.rst

humitos · 2022-05-30T15:18:51Z

docs/user/canonical-urls.rst

+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
+
+For :doc:`MkDocs </intro/getting-started-with-mkdocs>` this isn't done automatically,
+but you can use the site_url_ setting.
+
+.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url


These should probably be subsections with instead just 2 paragraph. Also, it could mention that this does not work with build.commands maybe...

Not sure how to split this into subsections, we need to add the description about the link tag and the warning to both, mkdocs and sphinx, we could move mkdocs paragraph about not being supported to a note instead

docs/user/canonical-urls.rst

humitos · 2022-05-30T15:19:52Z

docs/user/custom_domains.rst

-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.


It seems we lost this subsection in the refactor.

It's as a step when creating the domain https://github.com/readthedocs/readthedocs.org/pull/9266/files#diff-938211973d90543e901c5445def567dddb0542430d329c86285f88acf281e169R20

stsewd · 2022-05-31T18:50:01Z

but may not be too aligned with the marketing/narrative content we wanted to add to these feature pages. Is this going to be done in a different PR?

I'm not sure what you mean with that, in the original issue there isn't a description about that either.

ericholscher

initial review here. I have lots more feedback, would it be useful for me to just push up edits directly?

ericholscher · 2022-05-31T20:30:06Z

docs/user/canonical-urls.rst

+They are mainly used by search engines to link users to the correct
+version and domain of your documentation.
+
+.. _Canonical URLs: https://datatracker.ietf.org/doc/html/rfc6596


We definitely don't want to link to this. Perhaps https://developers.google.com/search/docs/advanced/crawling/consolidate-duplicate-urls?

ericholscher · 2022-05-31T20:31:27Z

docs/user/canonical-urls.rst

+For example, if you have a project named ``docs``
+with a custom domain ``https://docs.example.com``.
+A search engine like Google will index both domains, ``http://docs.readthedocs.io`` and
+``https://docs.example.com``.


Suggested change

For example, if you have a project named ``docs``

with a custom domain ``https://docs.example.com``.

A search engine like Google will index both domains, ``http://docs.readthedocs.io`` and

``https://docs.example.com``.

For example, if you have a project named ``example-docs``

with a custom domain ``https://docs.example.com``.

A search engine like Google will index both domains, ``http://example-docs.readthedocs.io`` and

``https://docs.example.com``.

docs as an example is confusing, since it's also the same URL we're hosting the content. Examples should always use example in them.

ericholscher · 2022-05-31T20:32:45Z

docs/user/canonical-urls.rst

+
+But you'll want to use ``https://docs.example.com`` as your canonical domain,
+this means that when Google indexes a page like ``https://docs.readthedocs.io/en/9.0/``,
+it will know that it should really point at ``https://docs.example.com/en/latest/``.
+


This feels really confusing to a user... I feel like we aren't explaining why this is useful here.

ericholscher · 2022-05-31T20:33:18Z

docs/user/canonical-urls.rst

+
+.. code-block:: html
+
+   <link rel="canonical" href="http://docs.fabfile.org/en/2.4/" />


This should use the example domain from above.

ericholscher · 2022-05-31T20:33:33Z

docs/user/canonical-urls.rst

+
+   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.


This is bad UX :( but not much we can do but document it for now.

This warning applies for both, mkdocs and sphinx, we should move it at the parent section maybe

ericholscher · 2022-05-31T20:33:57Z

docs/user/custom-domains.rst

+
+By default, your documentation is served from a Read the Docs :ref:`subdomain <hosting:subdomain support>` using the project's slug:
+``<slug>.readthedocs.io`` or ``<slug>.readthedocs-hosted.com`` for |com_brand|.
+For example if you import your project as ``docs``, it will be served from ``https://docs.readthedocs.io``.


Suggested change

For example if you import your project as ``docs``, it will be served from ``https://docs.readthedocs.io``.

For example if you import your project as ``example-docs``, it will be served from ``https://example-docs.readthedocs.io``.

docs/user/custom-domains.rst

ericholscher · 2022-05-31T20:49:46Z

docs/user/custom-domains.rst

+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.
+
+Certificate authority authorization


We should just remove this entire section. It isn't needed anymore.

stsewd · 2022-06-02T18:37:47Z

would it be useful for me to just push up edits directly?

@ericholscher sure, I have pushed some improvements from the review already.

ericholscher · 2022-06-08T21:55:07Z

I've just pushed up a bunch of edits in ddcab9d. With these I'm 👍 on merging, so just need someone else to review.

docs/user/canonical-urls.rst

agjohnson · 2022-06-09T00:33:06Z

docs/user/canonical-urls.rst

+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.


This feels redundant, and/or isn't adding much for the reader. Is there a specific reason worth mentioning why it isn't a great solution perhaps? If not, maybe worth skipping this sentence

Suggested change

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.

We need to justify why we're doing this. Users will likely be confused why this is happening if we don't explain the tradeoffs between not using canonical versions and indexing every version.

Agreed, but the sentence before describes the problem better. This sentences mostly distills down to "this is one imperfect solution to the problem we just outlined", and so sounds redundant, and isn't confident.

I'm suggesting either expanding on the problem/solution or dropping this sentence. Something like this expands on both:

Suggested change

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.

Linking to outdated documentation is confusing for your readers,

but this can be avoided by telling search engines exactly where to find your documentation.

docs/user/canonical-urls.rst

agjohnson · 2022-06-09T00:46:44Z

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``.


This is a term I'd love to phase out eventually

humitos · 2022-06-09T08:35:09Z

docs/user/custom-domains.rst

-this service is 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.
+managed by Cloudflare.


Maybe we can link to https://www.cloudflare.com/ here

@ericholscher not sure if you missed this or not --but there is no reaction: 👍🏼 or 👎🏼 ?

I don't really care. We can link to them, or not. 🤷 Definitely doesn't seem like a blocker though.

docs/user/custom-domains.rst

humitos · 2022-06-09T08:44:25Z

docs/user/custom-domains.rst

+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``.


Don't we include HSTS on readthedocs.build for a particular reason?

Guessing we just haven't done it yet.

docs/user/custom-domains.rst

ericholscher

Alright, addressed review feedback. 👍

ericholscher · 2022-06-09T20:20:13Z

docs/user/custom-domains.rst

+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``.


Guessing we just haven't done it yet.

humitos

LGTM! There is some checks failing, tho.

humitos · 2022-06-13T11:28:14Z

docs/user/custom-domains.rst

-this service is 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.
+managed by Cloudflare.


@ericholscher not sure if you missed this or not --but there is no reaction: 👍🏼 or 👎🏼 ?

This includes: * defining slugs * Clarifying removing domains * More selling of our custom header features

Co-authored-by: Anthony <[email protected]> Co-authored-by: Manuel Kaufmann <[email protected]>

stsewd force-pushed the update-custom-domain-docs branch 5 times, most recently from e7d4772 to e458023 Compare May 25, 2022 18:41

stsewd commented May 25, 2022

View reviewed changes

stsewd marked this pull request as ready for review May 25, 2022 18:47

stsewd requested a review from a team as a code owner May 25, 2022 18:47

auto-assign bot assigned stsewd May 25, 2022

stsewd force-pushed the update-custom-domain-docs branch from e458023 to 0d630c6 Compare May 26, 2022 21:19

humitos reviewed May 30, 2022

View reviewed changes

ericholscher reviewed May 31, 2022

View reviewed changes

agjohnson reviewed Jun 9, 2022

View reviewed changes

humitos reviewed Jun 9, 2022

View reviewed changes

ericholscher reviewed Jun 9, 2022

View reviewed changes

humitos approved these changes Jun 13, 2022

View reviewed changes

stsewd and others added 8 commits June 13, 2022 11:30

Docs: update custom domains docs

abed69c

Rename file

8b404cc

Updates from review

0028ff1

Updates from review

091584d

Lots of content updates on the custom domain pages.

fab4f1e

This includes: * defining slugs * Clarifying removing domains * More selling of our custom header features

Try to fix docs-lint

5ec88dd

One more try

4e18742

This should work

a75744f

ericholscher and others added 3 commits June 13, 2022 11:30

Apply suggestions from code review

a58173e

Co-authored-by: Anthony <[email protected]> Co-authored-by: Manuel Kaufmann <[email protected]>

Fix line endings

59f077e

Link to CF

4415907

ericholscher force-pushed the update-custom-domain-docs branch from 082f513 to 4415907 Compare June 13, 2022 18:30

ericholscher merged commit 79178c6 into main Jun 13, 2022

ericholscher deleted the update-custom-domain-docs branch June 13, 2022 19:55

shimizukawa mentioned this pull request Sep 3, 2022

sphinx-doc.org APEX domain setting for ReadTheDocs sphinx-doc/sphinx#10797

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: update custom domains docs #9266

Docs: update custom domains docs #9266

stsewd commented May 24, 2022 •

edited

Loading

stsewd May 25, 2022

humitos commented May 26, 2022

agjohnson commented May 26, 2022

stsewd commented May 26, 2022

humitos left a comment

humitos May 30, 2022

stsewd May 31, 2022

humitos May 30, 2022

stsewd May 31, 2022

stsewd commented May 31, 2022

ericholscher left a comment

ericholscher May 31, 2022

ericholscher May 31, 2022 •

edited

Loading

ericholscher May 31, 2022

ericholscher May 31, 2022 •

edited

Loading

ericholscher May 31, 2022 •

edited

Loading

stsewd Jun 9, 2022

ericholscher May 31, 2022

ericholscher May 31, 2022

stsewd commented Jun 2, 2022 •

edited

Loading

ericholscher commented Jun 8, 2022

agjohnson Jun 9, 2022

ericholscher Jun 9, 2022

agjohnson Jun 13, 2022

agjohnson Jun 9, 2022

humitos Jun 9, 2022

humitos Jun 13, 2022

ericholscher Jun 13, 2022 •

edited

Loading

humitos Jun 9, 2022

ericholscher Jun 9, 2022

ericholscher left a comment

ericholscher Jun 9, 2022

humitos left a comment

humitos Jun 13, 2022


		.. code-block:: html

		<link rel="canonical" href="http://docs.fabfile.org/en/2.4/" />

	For example if you import your project as ``docs``, it will be served from ``https://docs.readthedocs.io``.
	For example if you import your project as ``example-docs``, it will be served from ``https://example-docs.readthedocs.io``.

	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.

Docs: update custom domains docs #9266

Docs: update custom domains docs #9266

Conversation

stsewd commented May 24, 2022 • edited Loading

Choose a reason for hiding this comment

humitos commented May 26, 2022

agjohnson commented May 26, 2022

stsewd commented May 26, 2022

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented May 31, 2022

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher May 31, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher May 31, 2022 • edited Loading

Choose a reason for hiding this comment

ericholscher May 31, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented Jun 2, 2022 • edited Loading

ericholscher commented Jun 8, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher Jun 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented May 24, 2022 •

edited

Loading

ericholscher May 31, 2022 •

edited

Loading

ericholscher May 31, 2022 •

edited

Loading

ericholscher May 31, 2022 •

edited

Loading

stsewd commented Jun 2, 2022 •

edited

Loading

ericholscher Jun 13, 2022 •

edited

Loading