From 8b9e455d0f060e30df229b7ad3ee780d9f830ca0 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 8 Feb 2023 14:52:11 +0100 Subject: [PATCH 1/7] Transform the guide into an explanation with best practices, use Sphinx and MkDocs examples in tabs --- docs/user/glossary.rst | 4 + docs/user/guides/administrators.rst | 1 - docs/user/guides/technical-docs-seo-guide.rst | 145 +++++++++++------- docs/user/index.rst | 1 + 4 files changed, 94 insertions(+), 57 deletions(-) diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index 5a41b3febe0..2f834f520d6 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -14,6 +14,10 @@ so that you have a reference for how we're using them. Projects have a *default version*, usually the latest stable version of a project. The *default version* is the URL that is redirected to when a users loads the `/` URL for your project. + discoverability + A documentation page is said to be *discoverable* when a user that needs it can find it through various methods: + Navigation, searching and cross-references from other pages are the + Docs as Code A term used to describe the workflow of keeping documentation in a Git repository, along with source code. diff --git a/docs/user/guides/administrators.rst b/docs/user/guides/administrators.rst index 348ea8316cd..1fea4e60c09 100644 --- a/docs/user/guides/administrators.rst +++ b/docs/user/guides/administrators.rst @@ -16,7 +16,6 @@ have a look at our :doc:`/tutorial/index`. Connect your Read the Docs account to your Git repository Manage Custom Domains Enable Canonical URLs - technical-docs-seo-guide Use traffic analytics manage-translations-sphinx hiding-a-version diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst index 08542aed8b0..d579a9d9348 100644 --- a/docs/user/guides/technical-docs-seo-guide.rst +++ b/docs/user/guides/technical-docs-seo-guide.rst @@ -1,36 +1,25 @@ -Technical Documentation Search Engine Optimization (SEO) Guide -============================================================== +Search Engine Optimization (SEO) for documentation projects +=========================================================== .. meta:: :description lang=en: - Looking to optimize your Sphinx documentation for search engines? + Looking to optimize your documentation project for search engines? This SEO guide will help your docs be better understood by both people and crawlers as well as help you rank higher in search engine results. +This article explains how documentation can be optimized to appear in search results, +ultimately increasing traffic to your docs. -This guide will help you optimize your documentation for search engines -with the goal of increasing traffic to your docs. -While you optimize your docs to make them more crawler friendly for search engine spiders, +While you optimize your docs to make them more friendly for search engine spiders/crawlers, it's important to keep in mind that your ultimate goal is to make your docs -more discoverable for your users. -**You're trying to make sure that when a user types a question into a search engine -that is answerable by your documentation, that your docs appear in the results.** +more :term:`discoverable ` for your users. -This guide isn't meant to be your only resource on SEO, -and there's a lot of SEO topics not covered here. -For additional reading, please see the -:ref:`external resources ` section. +.. seealso:: -While many of the topics here apply to all forms of technical documentation, -this guide will focus on Sphinx, which is the most common -documentation authoring tool on Read the Docs, -as well as improvements provided by Read the Docs itself. - - -.. contents:: Table of contents - :local: - :backlinks: none - :depth: 3 + This guide isn't meant to be your only resource on SEO, + and there's a lot of SEO topics not covered here. + For additional reading, please see the + :ref:`external resources ` section. SEO Basics @@ -80,8 +69,8 @@ generates static HTML and the performance is typically decent relative to most of the internet. -Optimizing your docs for search engine spiders ----------------------------------------------- +Best practices for documentation SEO +------------------------------------ Once a crawler or spider finds your site, it will follow links and redirects in an attempt to find any and all pages on your site. @@ -92,30 +81,47 @@ which we'll discuss shortly, the most important thing is making sure the spider can follow links on your site and get to all your pages. -Avoid orphan pages -~~~~~~~~~~~~~~~~~~ +Avoid orphan pages ✅️ +~~~~~~~~~~~~~~~~~~~~~~ Sphinx calls pages that don't have links to them "orphans" and will throw a warning while building documentation that contains an orphan unless the warning is silenced with the :ref:`orphan directive `: -:: +.. tabs:: - $ make html - sphinx-build -b html -d _build/doctrees . _build/html - Running Sphinx v1.8.5 - ... - checking consistency... /path/to/file.rst: WARNING: document isn't included in any toctree - done - ... - build finished with problems, 1 warning. + .. tab:: Sphinx -You can make all Sphinx warnings into errors during your build process -by setting ``SPHINXOPTS = -W --keep-going`` in your Sphinx Makefile. + Sphinx will warn you when a page isn't referenced by the remaining documentation. + We recommend failing your builds whenever Sphinx warns you, + using the ``fail_on_warnings`` option in :ref:`.readthedocs.yaml `. + Here is an example of a warning of an unreferenced page:: -Avoid uncrawlable content -~~~~~~~~~~~~~~~~~~~~~~~~~ + $ make html + sphinx-build -b html -d _build/doctrees . _build/html + Running Sphinx v1.8.5 + ... + checking consistency... /path/to/file.rst: WARNING: document isn't included in any toctree + done + ... + build finished with problems, 1 warning. + + .. tab:: MkDocs + + MkDocs automatically includes all ``.md`` files in the main navigation 💯️. + So it does not need to report back about unreferenced files. + You have to go out of your way and install a plugin, + if you want to hide files from the navigation. + If you do want to scan your documentation for unreferenced files and images, + a plugin like `mkdocs-unused-files`_ does the job. + + +.. _mkdocs-unused-files: https://github.com/wilhelmer/mkdocs-unused-files + + +Avoid uncrawlable content ✅️ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ While typically this isn't a problem with technical documentation, try to avoid content that is "hidden" from search engines. @@ -125,20 +131,47 @@ For example, if you do have a video in your docs, make sure the rest of that page describes the content of the video. When using images, make sure to set the image alt text or set a caption on figures. -For Sphinx, the image and figure directives support this: -.. sourcecode:: rst +.. tabs:: + + .. tab:: Sphinx + + For Sphinx, the image and figure directives support both alt texts and captions: - .. image:: your-image.png - :alt: A description of this image + .. code-block:: rst - .. figure:: your-image.png + .. image:: your-image.png + :alt: A description of this image - A caption for this figure + .. figure:: your-image.png + A caption for this figure -Redirects -~~~~~~~~~ + .. tab:: MkDocs + + The Markdown syntax fundamentally prescribes an alt text for images: + + .. code-block:: md + + ![Image alt text](https://dummyimage.com/600x400/){ width="300" } + + If you want to use figures and captions, + Markdown and MkDocs do not have a built-in feature. + Instead, + you can use markdown extensions such as `md-in-html`_ to allow the necessary HTML structures for including figures: + + .. code-block:: md + +
+ ![Image alt text](https://dummyimage.com/600x400/){ width="300" } +
Image caption
+
+ +.. _md-in-html: https://python-markdown.github.io/extensions/md_in_html/ + + +Redirects ✅️ +~~~~~~~~~~~~~ Redirects tell search engines when content has moved. For example, if this guide moved from ``guides/technical-docs-seo-guide.html`` to ``guides/sphinx-seo-guide.html``, @@ -152,8 +185,8 @@ that should cover all the different cases such as redirecting a certain page for or redirecting one version to another. -Canonical URLs -~~~~~~~~~~~~~~ +Canonical URLs ✅️ +~~~~~~~~~~~~~~~~~~ Anytime very similar content is hosted at multiple URLs, it is pretty important to set a canonical URL. @@ -167,8 +200,8 @@ under :guilabel:`Admin` > :guilabel:`Domains` in the Read the Docs dashboard. -Use a robots.txt file -~~~~~~~~~~~~~~~~~~~~~ +Use a robots.txt file ✅️ +~~~~~~~~~~~~~~~~~~~~~~~~~ A ``robots.txt`` file is readable by crawlers and lives at the root of your site (eg. https://docs.readthedocs.io/robots.txt). @@ -186,8 +219,8 @@ See the `Google's documentation on robots.txt `. See the `Google docs on building a sitemap `_. -Use meta tags -~~~~~~~~~~~~~ +Use meta tags ✅️ +~~~~~~~~~~~~~~~~~ Using a meta description allows you to customize how your pages look in search engine result pages. diff --git a/docs/user/index.rst b/docs/user/index.rst index cdb91d8fab0..b769e719e34 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -88,6 +88,7 @@ to help you create fantastic documentation for your project. /science /commercial/organizations /automatic-redirects + /guides/technical-docs-seo-guide .. toctree:: :maxdepth: 2 From 8ca64985f57b8bf1b754961da892b97bb0c783ff Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Thu, 9 Feb 2023 17:16:35 +0100 Subject: [PATCH 2/7] Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/user/guides/technical-docs-seo-guide.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst index d579a9d9348..762b8b7ed95 100644 --- a/docs/user/guides/technical-docs-seo-guide.rst +++ b/docs/user/guides/technical-docs-seo-guide.rst @@ -110,10 +110,9 @@ unless the warning is silenced with the :ref:`orphan directive .. tab:: MkDocs MkDocs automatically includes all ``.md`` files in the main navigation 💯️. - So it does not need to report back about unreferenced files. - You have to go out of your way and install a plugin, - if you want to hide files from the navigation. - If you do want to scan your documentation for unreferenced files and images, + This makes sure that all files are discoverable by default, + however there are configurations that allow for unlinked files in various ways. + If you want to scan your documentation for unreferenced files and images, a plugin like `mkdocs-unused-files`_ does the job. @@ -149,13 +148,13 @@ When using images, make sure to set the image alt text or set a caption on figur .. tab:: MkDocs - The Markdown syntax fundamentally prescribes an alt text for images: + The Markdown syntax defines an alt text for images: .. code-block:: md ![Image alt text](https://dummyimage.com/600x400/){ width="300" } - If you want to use figures and captions, + Though HTML supports figures and captions, Markdown and MkDocs do not have a built-in feature. Instead, you can use markdown extensions such as `md-in-html`_ to allow the necessary HTML structures for including figures: From d211a9d181be6e3eafd9330b6849e59a698d7df1 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 9 Feb 2023 17:30:09 +0100 Subject: [PATCH 3/7] Re-add motivational text with a reference to the best practices.. but can't be **bold** because reST --- docs/user/guides/technical-docs-seo-guide.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst index 762b8b7ed95..037bc6d0a35 100644 --- a/docs/user/guides/technical-docs-seo-guide.rst +++ b/docs/user/guides/technical-docs-seo-guide.rst @@ -14,6 +14,10 @@ While you optimize your docs to make them more friendly for search engine spider it's important to keep in mind that your ultimate goal is to make your docs more :term:`discoverable ` for your users. +By following :ref:`best practices for SEO `, +you can ensure that when a user types a question into a search engine, +they can get the answers from your documentation in the search results. + .. seealso:: This guide isn't meant to be your only resource on SEO, From 6d716eef0b11028e3762da0c4e13fa6e1ed13e06 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 9 Feb 2023 19:05:47 +0100 Subject: [PATCH 4/7] Finish the sentence --- docs/user/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index 2f834f520d6..8755eafc01f 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -16,7 +16,7 @@ so that you have a reference for how we're using them. discoverability A documentation page is said to be *discoverable* when a user that needs it can find it through various methods: - Navigation, searching and cross-references from other pages are the + Navigation, in-docs searching, cross-references from other pages, and search engine optimization are the most typical ways of making content *discoverable*. Docs as Code A term used to describe the workflow of keeping documentation in a Git repository, From d5cb3f6dfa921cda132870ef9946394f9afc8151 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 9 Feb 2023 19:11:33 +0100 Subject: [PATCH 5/7] General intro to unlinked pages --- docs/user/guides/technical-docs-seo-guide.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst index 037bc6d0a35..119d36bf64e 100644 --- a/docs/user/guides/technical-docs-seo-guide.rst +++ b/docs/user/guides/technical-docs-seo-guide.rst @@ -85,18 +85,23 @@ which we'll discuss shortly, the most important thing is making sure the spider can follow links on your site and get to all your pages. -Avoid orphan pages ✅️ -~~~~~~~~~~~~~~~~~~~~~~ +Avoid unlinked pages ✅️ +~~~~~~~~~~~~~~~~~~~~~~~~ + +When building your documentation, +you should ensure that pages aren't *unlinked* or *orphaned*, +meaning that no other pages or navigation have a link to them. -Sphinx calls pages that don't have links to them "orphans" -and will throw a warning while building documentation that contains an orphan -unless the warning is silenced with the :ref:`orphan directive `: +Search engine crawlers will not discover pages that aren't referenced. .. tabs:: .. tab:: Sphinx - Sphinx will warn you when a page isn't referenced by the remaining documentation. + Sphinx calls pages that don't have links to them "orphans" + and will throw a warning while building documentation that contains an orphan + unless the warning is silenced with the :ref:`orphan directive `. + We recommend failing your builds whenever Sphinx warns you, using the ``fail_on_warnings`` option in :ref:`.readthedocs.yaml `. From 8e93993fc6ce73adf10a734f97ec54da97225157 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 9 Feb 2023 19:35:03 +0100 Subject: [PATCH 6/7] Add TODO items --- docs/user/guides/technical-docs-seo-guide.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst index 119d36bf64e..d93e818df26 100644 --- a/docs/user/guides/technical-docs-seo-guide.rst +++ b/docs/user/guides/technical-docs-seo-guide.rst @@ -94,6 +94,8 @@ meaning that no other pages or navigation have a link to them. Search engine crawlers will not discover pages that aren't referenced. +.. TODO: Create a "generic" tab? + .. tabs:: .. tab:: Sphinx @@ -140,6 +142,8 @@ make sure the rest of that page describes the content of the video. When using images, make sure to set the image alt text or set a caption on figures. +.. TODO: Create a "generic" tab? + .. tabs:: .. tab:: Sphinx From 5470dc0d00d39682f9c067bad372c90421f8f6fc Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Fri, 10 Feb 2023 13:55:50 +0100 Subject: [PATCH 7/7] Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/user/glossary.rst | 2 +- docs/user/guides/technical-docs-seo-guide.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index 8755eafc01f..044fdd40a2a 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -16,7 +16,7 @@ so that you have a reference for how we're using them. discoverability A documentation page is said to be *discoverable* when a user that needs it can find it through various methods: - Navigation, in-docs searching, cross-references from other pages, and search engine optimization are the most typical ways of making content *discoverable*. + Navigation, search, and links from other pages are the most typical ways of making content *discoverable*. Docs as Code A term used to describe the workflow of keeping documentation in a Git repository, diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst index d93e818df26..d421c4a62be 100644 --- a/docs/user/guides/technical-docs-seo-guide.rst +++ b/docs/user/guides/technical-docs-seo-guide.rst @@ -14,7 +14,7 @@ While you optimize your docs to make them more friendly for search engine spider it's important to keep in mind that your ultimate goal is to make your docs more :term:`discoverable ` for your users. -By following :ref:`best practices for SEO `, +By following :ref:`our best practices for SEO `, you can ensure that when a user types a question into a search engine, they can get the answers from your documentation in the search results. @@ -89,10 +89,10 @@ Avoid unlinked pages ✅️ ~~~~~~~~~~~~~~~~~~~~~~~~ When building your documentation, -you should ensure that pages aren't *unlinked* or *orphaned*, +you should ensure that pages aren't *unlinked*, meaning that no other pages or navigation have a link to them. -Search engine crawlers will not discover pages that aren't referenced. +Search engine crawlers will not discover pages that aren't linked from somewhere else on your site. .. TODO: Create a "generic" tab?