Merge pull request #17 from practical-python-org/SEO

google search console and SEO things

Author: Xarlos89

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
         entry: uv run zensical build --strict --clean
         language: system
         pass_filenames: false
-        files: ^(docs/|zensical\.toml|pyproject\.toml|uv\.lock)
+        files: ^(docs/|overrides/|zensical\.toml|pyproject\.toml|uv\.lock)
 
   - repo: https://github.com/swiss-ai-center/mdwrap
     rev: 0.2.5

README.md

@@ -43,6 +43,7 @@ uv run --dev pre-commit run --all-files
 docs/
 ├── index.md               landing page
 ├── CNAME                  custom domain, copied to the site root on build
+├── robots.txt             Tells crawlers and bots where to go
 ├── stylesheets/           colour, font and hero overrides
 ├── static/                logo and images
 ├── getting-started/       the entry point for new members
@@ -53,6 +54,8 @@ docs/
 │   ├── our-projects/      software the community maintains
 │   └── build-something/   project challenges for members
 └── code-adventure/        landing page for the Code Adventure puzzles!
+overrides/
+└── main.html              theme override adding Open Graph and other SEO tags
 scripts/
 └── refresh_member_count.py  updates the Discord member count before a deploy build
 zensical.toml              all site configuration, including the nav

docs/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://practicalpython.org/sitemap.xml

overrides/main.html

@@ -0,0 +1,60 @@
+{#-
+  Theme override: extends Zensical's base template to add the SEO tags it
+  doesn't emit on its own. Wired up by custom_dir in zensical.toml.
+-#}
+{% extends "base.html" %}
+
+{#- page.is_homepage is never set by Zensical, so compare URLs instead. -#}
+{% set is_homepage = page.canonical_url == config.site_url %}
+
+{#- The nav labels the homepage "Home", which would otherwise become its title. -#}
+{% block htmltitle %}
+  {% if is_homepage %}
+    <title>{{ config.site_name }}</title>
+  {% else %}
+    {{ super() }}
+  {% endif %}
+{% endblock %}
+
+{% block extrahead %}
+  {% if is_homepage %}
+    {% set title = config.site_name %}
+  {% elif page.meta and page.meta.title %}
+    {% set title = page.meta.title %}
+  {% elif page.title %}
+    {% set title = page.title | striptags %}
+  {% else %}
+    {% set title = config.site_name %}
+  {% endif %}
+  {% if page.meta and page.meta.description %}
+    {% set description = page.meta.description %}
+  {% else %}
+    {% set description = config.site_description %}
+  {% endif %}
+  {% set is_post = page.meta and page.meta.date %}
+
+  {#- Open Graph: the preview card Discord, Slack and friends render for a link. -#}
+  <meta property="og:type" content="{{ 'article' if is_post else 'website' }}">
+  <meta property="og:site_name" content="{{ config.site_name }}">
+  <meta property="og:title" content="{{ title }}">
+  <meta property="og:description" content="{{ description }}">
+  {% if page.canonical_url %}
+    <meta property="og:url" content="{{ page.canonical_url }}">
+  {% endif %}
+  {% if is_post %}
+    <meta property="article:published_time" content="{{ page.meta.date }}">
+  {% endif %}
+  <meta name="twitter:card" content="summary">
+
+  {#- Tells Google the site's name, shown above results instead of the bare domain. -#}
+  {% if is_homepage %}
+    <script type="application/ld+json">
+      {
+        "@context": "https://schema.org",
+        "@type": "WebSite",
+        "name": {{ config.site_name | tojson }},
+        "url": {{ config.site_url | tojson }}
+      }
+    </script>
+  {% endif %}
+{% endblock %}

zensical.toml

@@ -59,6 +59,8 @@ nav = [
 
 [project.theme]
 language = "en"
+# Template overrides: overrides/main.html adds Open Graph tags and the like.
+custom_dir = "overrides"
 features = [
   "content.action.edit",
   "content.code.annotate",