Write a proper README

Describes the theme's look, features, and file structure, plus the
custom pelicanconf.py settings it reads (SOCIAL, SITE_COMMIT/
SITE_BRANCH, sidebar display toggles) for anyone else adopting it.

README.md

@@ -1,4 +1,30 @@
 # Pelican LaTeX theme
 
-A theme for pelican which mimics the look of LaTeX documents.
+A theme for [Pelican](https://getpelican.com/) that mimics the look and feel of a LaTeX-typeset document — serif typography (bundled Latin Modern webfonts), justified body text, and syntax-highlighted code blocks styled to match.
 
+## Features
+
+- Light and dark mode, plus a choice of accent color, all switchable at runtime and remembered across visits
+- A serif/sans-serif font toggle for readers who prefer either look
+- Sidebar navigation with pages, recent articles, categories, and a weighted tag cloud
+- Built-in support for multilingual sites built with Pelican's `i18n_subsites` plugin, including a language switcher and per-page translation links
+- Lightbox viewer for images, and inline SVG handling that lets diagrams adapt their colors to the current light/dark theme
+- A small, optional row of social/profile link icons
+
+## Structure
+
+- `templates/` — Jinja2 templates for articles, pages, listing views (archives, tags, categories, authors), and shared partials
+- `static/css/` — the theme's stylesheet and Pygments syntax-highlighting themes
+- `static/js/` — the theme/accent/font toggles, lightbox, and SVG handling
+- `static/fonts/` — the bundled Latin Modern webfonts
+
+To use the theme, point a Pelican site's `THEME` setting at this repository (or a submodule checkout of it).
+
+## Configuration
+
+Beyond Pelican's standard settings, the theme reads a few of its own from `pelicanconf.py`:
+
+- `SOCIAL` — a tuple of `(name, url, icon_slug)` entries for the social/profile link row. `icon_slug` must match an SVG file in `templates/icons/<icon_slug>.svg`; currently bundled are `github`, `linkedin`, `orcid`, `mastodon`, `bluesky`, and `matrix`. Add more by dropping in another icon file with a matching slug. Leave `SOCIAL` unset to omit the row entirely.
+- `SITE_COMMIT` and `SITE_BRANCH` — optional build identifiers shown as a small line in the footer (e.g. "Build abc1234 (main)"), linked to the commit on Gitea. Meant to be set from a CI environment rather than hand-written; the footer line is omitted if `SITE_COMMIT` is empty.
+
+The sidebar sections can also be toggled individually, following the same convention as Pelican's default theme: `DISPLAY_PAGES_ON_MENU` and `DISPLAY_CATEGORIES_ON_MENU` (both off unless set to `True`), and `DISPLAY_RECENT_ARTICLES_ON_MENU`/`DISPLAY_TAG_CLOUD_ON_MENU` (both on by default). `RECENT_ARTICLES_COUNT` caps the recent-articles list (default 10).

static/css/site.css

@@ -386,24 +386,66 @@ ul.menuitems {
   content: "Translations: ";
 }
 
-html[lang="de"] {
+/* "ul.social-links", not ".social-links": the global reset rule
-  #pages:before {
+   (body, h1, ..., ul[class], ol[class], ..., dd { margin: 0; }) matches
-    content: "Seiten:";
+   via ul[class] at specificity (0,0,1,1), which beats a plain single-class
+   selector like ".social-links" (0,0,1,0) regardless of source order.
+   Adding the "ul" type selector ties it at (0,0,1,1), so this rule (being
+   later in the file) wins instead of always being zeroed back out. */
+ul.social-links {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.75rem;
+  list-style: none;
+  /* Clearly more than double the standard 3rem inter-section gap (e.g.
+     the gap above "Tags:") to set the icon row apart from the sidebar nav. */
+  margin: 10rem 0 0 0;
 }
 
-  #recent-articles:before {
+.social-links li {
-    content: "Neueste Artikel:";
+  margin: 0;
 }
 
-  #categories:before {
+.social-links a {
-    content: "Kategorien:";
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--main-link-color);
+  opacity: 0.85;
+  transition: opacity 0.15s ease;
 }
 
-  #translations:before {
+.social-links a:hover,
-    content: "Übersetzungen:";
+.social-links a:focus-visible {
+  opacity: 1;
 }
+
+.social-links svg {
+  width: 1.25rem;
+  height: 1.25rem;
 }
 
+/* About-me page variant: bigger icons, even gap above/below the divider.
+   "ul.social-links--large" for the same specificity reason as above. */
+ul.social-links--large {
+  margin-top: 5rem;
+  gap: 1.5rem;
+}
+
+.social-links--large svg {
+  width: 5rem;
+  height: 5rem;
+}
+
+.social-links-divider {
+  border: none;
+  border-top: 1px solid var(--table-border-color);
+  width: 4rem;
+  margin: 5rem auto 0 auto;
+}
+
+
 .menuitems {
   list-style: none;
   margin: 3rem 0 0 0;
@@ -617,13 +659,16 @@ svg.injected-svg tspan {
   cursor: zoom-in;
 }
 
-.entry-content img~em{
+.entry-content img~em,
+.entry-content svg.injected-svg~em{
   display: block;
   margin: 0 auto 0 auto;
   text-align: center;
   font-style: normal;
 }
-.entry-content img~em:before {
+
+.entry-content img~em:before,
+.entry-content svg.injected-svg~em:before {
   content: 'Figure ' counter(figures) ': ';
   font-weight: bold;
 }
@@ -682,6 +727,10 @@ svg.injected-svg tspan {
   font-weight: bold;
 }
 
+.lightbox-overlay #lightbox-caption .fig-number:before {
+  content: 'Figure ' attr(data-num) ': ';
+}
+
 /* Fallback: Systemeinstellung, nur falls kein manueller Override gesetzt ist */
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) .lightbox-overlay {
@@ -838,3 +887,39 @@ svg.injected-svg tspan {
 .footnotes {
   border-top: 1px solid hsl(0, 0%, 39%);
 }
+
+html[lang="de"] {
+  #pages:before {
+    content: "Seiten:";
+  }
+
+  #recent-articles:before {
+    content: "Neueste Artikel:";
+  }
+
+  #categories:before {
+    content: "Kategorien:";
+  }
+
+  #translations:before {
+    content: "Übersetzungen:";
+  }
+
+  .entry-content img~em:before,
+  .entry-content svg.injected-svg~em:before {
+    content: 'Abbildung ' counter(figures) ': ';
+  }
+
+  .entry-content table~p > em:before {
+    content: 'Tabelle ' counter(tables) ': ';
+  }
+
+  .entry-content table.highlighttable~p > em:before,
+  .entry-content div.highlight~p > em:before {
+    content: 'Liste ' counter(listings) ': ';
+  }
+
+  .lightbox-overlay #lightbox-caption .fig-number:before {
+    content: 'Abbildung ' attr(data-num) ': ';
+  }
+}

static/js/lightbox.js

@@ -23,7 +23,7 @@ document.addEventListener('DOMContentLoaded', function () {
 
   function setCaption(figureNumber, captionText) {
     overlayCaption.innerHTML = captionText
-      ? '<span class="fig-number">Figure ' + figureNumber + ':</span> ' + captionText
+      ? '<span class="fig-number" data-num="' + figureNumber + '"></span> ' + captionText
       : '';
   }
 

templates/base.html

@@ -11,6 +11,9 @@
 
     <link rel="stylesheet" type="text/css" href="{{ main_siteurl | default(SITEURL) }}/theme/css/site.css" />
 
+    {% if EXTRA_HEAD %}
+      {{ EXTRA_HEAD | safe }}
+    {% endif %}
     {% if FEED_ALL_ATOM %}
     <link href="{{ FEED_DOMAIN }}/{% if FEED_ALL_ATOM_URL %}{{ FEED_ALL_ATOM_URL }}{% else %}{{ FEED_ALL_ATOM }}{% endif %}" type="application/atom+xml" rel="alternate" title="{{ SITENAME }} Full Atom Feed" />
     {% endif %}
@@ -110,6 +113,7 @@
       </ul>
       {% endif %}
       {% endif %}
+      {% include "includes/social_links.html" %}
     </nav><!-- /#menu -->
     <main id="content">
     {% block content %}
@@ -120,6 +124,9 @@
   <footer id="contentinfo" class="body">
     <address id="about" class="vcard body">
       Proudly powered by <a href="http://getpelican.com/">Pelican</a>, which takes great advantage of <a href="http://python.org">Python</a>.
+      {% if SITE_COMMIT %}
+      <span class="header-delimiter">·</span> Build <a href="https://git.haemka.in/hmk/haemka.de/commit/{{ SITE_COMMIT }}">{{ SITE_COMMIT }}</a> ({{ SITE_BRANCH }})
+      {% endif %}
     </address><!-- /#about -->
   </footer><!-- /#contentinfo -->
 

templates/icons/bluesky.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor" aria-hidden="true" focusable="false"><title>Bluesky</title><path d="M5.202 2.857C7.954 4.922 10.913 9.11 12 11.358c1.087-2.247 4.046-6.436 6.798-8.501C20.783 1.366 24 .213 24 3.883c0 .732-.42 6.156-.667 7.037-.856 3.061-3.978 3.842-6.755 3.37 4.854.826 6.089 3.562 3.422 6.299-5.065 5.196-7.28-1.304-7.847-2.97-.104-.305-.152-.448-.153-.327 0-.121-.05.022-.153.327-.568 1.666-2.782 8.166-7.847 2.97-2.667-2.737-1.432-5.473 3.422-6.3-2.777.473-5.899-.308-6.755-3.369C.42 10.04 0 4.615 0 3.883c0-3.67 3.217-2.517 5.202-1.026"/></svg>

templates/icons/github.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor" aria-hidden="true" focusable="false"><title>GitHub</title><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>

templates/icons/linkedin.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor" aria-hidden="true" focusable="false"><title>LinkedIn</title><path d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z"/></svg>

templates/icons/mastodon.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor" aria-hidden="true" focusable="false"><title>Mastodon</title><path d="M23.268 5.313c-.35-2.578-2.617-4.61-5.304-5.004C17.51.242 15.792 0 11.813 0h-.03c-3.98 0-4.835.242-5.288.309C3.882.692 1.496 2.518.917 5.127.64 6.412.61 7.837.661 9.143c.074 1.874.088 3.745.26 5.611.118 1.24.325 2.47.62 3.68.55 2.237 2.777 4.098 4.96 4.857 2.336.792 4.849.923 7.256.38.265-.061.527-.132.786-.213.585-.184 1.27-.39 1.774-.753a.057.057 0 0 0 .023-.043v-1.809a.052.052 0 0 0-.02-.041.053.053 0 0 0-.046-.01 20.282 20.282 0 0 1-4.709.545c-2.73 0-3.463-1.284-3.674-1.818a5.593 5.593 0 0 1-.319-1.433.053.053 0 0 1 .066-.054c1.517.363 3.072.546 4.632.546.376 0 .75 0 1.125-.01 1.57-.044 3.224-.124 4.768-.422.038-.008.077-.015.11-.024 2.435-.464 4.753-1.92 4.989-5.604.008-.145.03-1.52.03-1.67.002-.512.167-3.63-.024-5.545zm-3.748 9.195h-2.561V8.29c0-1.309-.55-1.976-1.67-1.976-1.23 0-1.846.79-1.846 2.35v3.403h-2.546V8.663c0-1.56-.617-2.35-1.848-2.35-1.112 0-1.668.668-1.67 1.977v6.218H4.822V8.102c0-1.31.337-2.35 1.011-3.12.696-.77 1.608-1.164 2.74-1.164 1.311 0 2.302.5 2.962 1.498l.638 1.06.638-1.06c.66-.999 1.65-1.498 2.96-1.498 1.13 0 2.043.395 2.74 1.164.675.77 1.012 1.81 1.012 3.12z"/></svg>

templates/icons/matrix.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor" aria-hidden="true" focusable="false"><title>Matrix</title><path d="M.632.55v22.9H2.28V24H0V0h2.28v.55zm7.043 7.26v1.157h.033c.309-.443.683-.784 1.117-1.024.433-.245.936-.365 1.5-.365.54 0 1.033.107 1.481.314.448.208.785.582 1.02 1.108.254-.374.6-.706 1.034-.992.434-.287.95-.43 1.546-.43.453 0 .872.056 1.26.167.388.11.716.286.993.53.276.245.489.559.646.951.152.392.23.863.23 1.417v5.728h-2.349V11.52c0-.286-.01-.559-.032-.812a1.755 1.755 0 0 0-.18-.66 1.106 1.106 0 0 0-.438-.448c-.194-.11-.457-.166-.785-.166-.332 0-.6.064-.803.189a1.38 1.38 0 0 0-.48.499 1.946 1.946 0 0 0-.231.696 5.56 5.56 0 0 0-.06.785v4.768h-2.35v-4.8c0-.254-.004-.503-.018-.752a2.074 2.074 0 0 0-.143-.688 1.052 1.052 0 0 0-.415-.503c-.194-.125-.476-.19-.854-.19-.111 0-.259.024-.439.074-.18.051-.36.143-.53.282-.171.138-.319.337-.439.595-.12.259-.18.6-.18 1.02v4.966H5.46V7.81zm15.693 15.64V.55H21.72V0H24v24h-2.28v-.55z"/></svg>

templates/icons/orcid.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="currentColor" aria-hidden="true" focusable="false"><title>ORCID</title><path d="M12 0C5.372 0 0 5.372 0 12s5.372 12 12 12 12-5.372 12-12S18.628 0 12 0zM7.369 4.378c.525 0 .947.431.947.947s-.422.947-.947.947a.95.95 0 0 1-.947-.947c0-.525.422-.947.947-.947zm-.722 3.038h1.444v10.041H6.647V7.416zm3.562 0h3.9c3.712 0 5.344 2.653 5.344 5.025 0 2.578-2.016 5.025-5.325 5.025h-3.919V7.416zm1.444 1.303v7.444h2.297c3.272 0 4.022-2.484 4.022-3.722 0-2.016-1.284-3.722-4.097-3.722h-2.222z"/></svg>

templates/includes/social_links.html

@@ -0,0 +1,7 @@
+{% if SOCIAL %}
+<ul class="social-links{% if social_links_variant %} social-links--{{ social_links_variant }}{% endif %}">
+  {% for name, url, icon in SOCIAL %}
+  <li><a href="{{ url }}" rel="me" aria-label="{{ name }}" title="{{ name }}">{% include "icons/" ~ icon ~ ".svg" %}</a></li>
+  {% endfor %}
+</ul>
+{% endif %}

templates/page.html

@@ -19,6 +19,12 @@
 
     {{ page.content }}
 
+    {% if page.slug == 'about-me' %}
+    <hr class="social-links-divider">
+    {% set social_links_variant = 'large' %}
+    {% include "includes/social_links.html" %}
+    {% endif %}
+
     {% if page.modified %}
         <p>
         Last updated: {{ page.locale_modified }}