Setting Up this 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.

Components

• Pelican

  • Flex Theme (heavily modified by now)
  • KaTeX plugin
  • pelican-cite (BibTeX-based citations)
  • pelican-toc (Article TOC's)
  • asciidoc-reader (AsciiDoc support)
  • series (Article Series)

• KaTeX

• Asciidoctor

  • katex (gem)
  • asciidoctor-katex

• Markdown extensions:

  • Standard extensions:

    • attr_list
    • footnotes

  • Third-party:

    • mdx_include (Markdown includes)

Installation

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):

node:

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

python:

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

ruby:

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

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.

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