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.

Components

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.7.4\python-3.7.4.amd64\Scripts for pip-installed components (Pelican)
  • Ruby path

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

  • npm install katex
  • npm install less (minimal css files for themes)
  • npm install less-plugin-clean-css
  • 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

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 (pelicanconf.py)

# markup-specific extensions and settings

ASCIIDOC_CMD = "asciidoctor"
ASCIIDOC_OPTIONS = ["-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",
}