From 186e0fd86af1fbb481fe30a9b109aa646e3c8fe8 Mon Sep 17 00:00:00 2001 From: haemka Date: Fri, 14 Aug 2026 17:28:35 +0000 Subject: [PATCH] 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 | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e894180..225bac6 100644 --- a/README.md +++ b/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/.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).