Making sure our docs are SEO optimized

[idomic]

https://docs.readthedocs.io/en/stable/guides/technical-docs-seo-guide.html

[yafimvo]

I went over the doc and ran SEO tests on our docs and compared it with some other similar docs. I took the jupysql docs as an example.

According to this article, we are OK. Our robots.txt and sitemap.xml are in place and everything is linked. butm there is a place for improvement. Unfortunately, since we're using an auto doc builder like jupyter-book, I'm not sure it's that easy though (e.g: our links and headers are generated automatically).

Our score

Jupyter-book score

Sphinx docs

Solution

I think the easiest and most effective thing we can start with is adding metadata tags to our docs.

Add RestructuredText to rst files

.. meta::
    :description lang=en:
        A brief explanation of the content and purpose of this page

Add html_meta to every md files

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.14.4
kernelspec:
  display_name: Python 3 (ipykernel)
  language: python
  name: python3
html_meta:
  "description lang=en": "Some description"
  "keywords": "Key1, Key2"
  "property=og:locale": "en_US"  
---

@edublancas @idomic
We need to decide which tags to use and how to describe every article.

[edublancas]

is there a way to add keywords to rst files?

---

I opened issues to track adding the metadata:

ploomber/jupysql#132
#290
ploomber/ploomber-engine#48

but let's keep this open so we revisit our SEO scores once those are in

[yafimvo]

is there a way to add keywords to rst files?

yes

.. meta::
    :description lang=en:
        Some description
    :keywords: Tag1, Tag2

[edublancas]

To add metadata to a notebook:

    "html_meta": {
        "description lang=en": "Description",
        "keywords": "Key1, Key2",
        "property=og:locale": "en_US"
    }