From a4dd790758d97d1ce2b3fa34800ea5a197b95a6b Mon Sep 17 00:00:00 2001
From: Xarlos <57622136+Xarlos89@users.noreply.github.com>
Date: Sat, 10 Oct 2026 17:19:37 +0200
Subject: [PATCH] google search consile and SEO things

---
 .pre-commit-config.yaml |  2 +-
 README.md               |  3 +++
 docs/robots.txt         |  4 +++
 overrides/main.html     | 60 +++++++++++++++++++++++++++++++++++++++++
 zensical.toml           |  2 ++
 5 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 docs/robots.txt
 create mode 100644 overrides/main.html

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index a1e037f..d7b5fe2 100644
--- a/.pre-commit-config.yaml
+++ b/.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
diff --git a/README.md b/README.md
index fb16a35..ead5b7f 100644
--- a/README.md
+++ b/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
diff --git a/docs/robots.txt b/docs/robots.txt
new file mode 100644
index 0000000..09ad67f
--- /dev/null
+++ b/docs/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://practicalpython.org/sitemap.xml
diff --git a/overrides/main.html b/overrides/main.html
new file mode 100644
index 0000000..83f422b
--- /dev/null
+++ b/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 %}
diff --git a/zensical.toml b/zensical.toml
index de8ac34..60800c8 100644
--- a/zensical.toml
+++ b/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",