Setting Up this Blog

Posted on Fri 14 February 2020 in blog

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.



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

  • Python
  • Node
  • Ruby (for Asciidoctor)

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

  • Node installation root (for katex.cmd)
  • Python scripting path ( Something like V:\bin\scripting\python\3.10.5\python-3.10.5.amd64\Scripts for pip-installed components (Pelican)
  • Ruby path

Do this from the scripting languages root or bin directory (even if in path):


  1. npm init (otherwise, nodes complete node_module sub-dir will be purged from most packages)
  2. npm install katex
  3. npm install less (minimal css files for themes)
  4. npm install less-plugin-clean-css
  5. Updating npm itself for portable installations on Windows:
  • Rename npm.cmd and npm into npm_.cmd and npm_
  • Do the same for npx.*
  • Run npm_ install -g npm@latest
  • Remove the underscored variants
  • ... or simply burn the whole thing and reapply 1.-4. from above


  • pip install pelican
  • pip install pybtex (for pelican-cite)
  • pip install beautifulsoup4 (for pelican-toc)
  • pip install mdx_include


  • gem install asciidoctor
  • gem install katex
  • gem install asciidoctor-katex (Broken [2023-01-21] - will not work with newer Asciidoctor versions1).

Pelican maintains two git submodules for his approved themes and plugins. 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):

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

Markdown, ReST and AsciiDoc options (

# markup-specific extensions and settings

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

    "footnote_references": "superscript",

    #    '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",

[1]I'm maintaining a local version of the gem with a workaround, until this is fixed upstream.