Setting Up this Blog

Posted on Fr 14 Februar 2020 in blog
Modified on Mi 12 Februar 2025

Technical Objectives

A JavaScript-free static page (with the occasional exception of D3/three.js plots), that supports mathematical content. In particular, formulas should not depend on any scripting. For this purpose a combination of Pelican and KaTeX was chosen. In contrast to MathJax (according to my knowledge), KaTeX can be utilized as an offline renderer.

Furthermore Markdown , reStructuredText and AsciiDoc support was a requirement.

The following is slightly Windows-centric, but should be easily transferable to other systems.

Components

Installation

For these instructions, the existence of the following scripting environments is a prerequisite (portable flavours exist for any of them):

  • Python uv maintained venv
  • Node "Standalone binary(.zip)" (for KaTeX, less, Asciidoctor + asciidoctor-katex (JS versions))

These are the collected PATH changes, required or optional for later setup steps (but see below).

  • Node installation root (node, npm) and ${NODE_PATH}/.bin (katex, less, asciidoctor - NODE_PATH is <node_root>/node_modules)
  • Python scripting path (provided from venv)

Node:

  1. npm install katex less less-plugin-clean-css asciidoctor asciidoctor-katex --save

(For local use, KaTeX fonts and CSS can be found in ${NODE_PATH}/katex/dist)

Python:

  • uv add setuptools esbonio beautifulsoup4 docopt markdown markdown-captions mdx_include
  • uv add pelican pybtex pelican-katex pelican-more-categories pelican-series

Pelican maintains two git submodules for his approved themes and legacy plugins (newer ones are here). I have a certain reluctance to submodules and so I'm holding copies in the blogs own git/folder structure.

Flex theme

  • Change link color variables into green (themes\flex\static\stylesheet\variables.less):
    @orange: rgb(0, 128, 0);
@light-orange: rgb(6, 160, 6);

(Yeah, this isn't orange anymore)

Apply changes to themes/flex/static/stylesheet/style.less (includes variables.less):

lessc --plugin=less-plugin-clean-css="advanced" style.less style.min.css

Markdown, ReST and AsciiDoc options (pelicanconf.py)

# markup-specific extensions and settings

ASCIIDOC_CMD = "asciidoctor"
# ASCIIDOC_OPTIONS = ["-r asciidoctor-katex"]
ASCIIDOC_OPTIONS = ["--trace -r asciidoctor-katex"]

DOCUTILS_SETTINGS = {
    "footnote_references": "superscript",
}

MARKDOWN = {
    #    'extensions': ['mdx_include',],
    "extension_configs": {
        "markdown.extensions.codehilite": {"css_class": "highlight"},
        "markdown.extensions.extra": {},
        "markdown.extensions.meta": {},
        "markdown.extensions.footnotes": {},
        "mdx_include": {"base_path": PATH},
        "attr_list": {},
    },
    "output_format": "html5",
}