Code highlighting, tables and maths with Python markdown

Caitra-S9 ☆9 1946 S.E.

Wishing you all a happy Ṡrī Rāma Navami! May Lord Ṡrīrāma grant us His divine mercy. The daily nakshatra at sunrise is expected to be Punarvasu (☆7) but it could sometimes be Ārdra (☆6) or Puṣya (☆8). But today is actually Āṡlēṣā (☆9). Can you guess why? It is because we’re using the sidereal (nirayana) months! If you use the tropical lunisolar (not solar) calendar, today is actually Vaiṡākha-S9, the Caitra-S9 being in the previous month 18-Mar-2024 which had both ☆6 + ☆7 during the civil day. Probably that was originally the day of celebration.

I have so far used Multimarkdown (MMD) and ReStructuredText (RST) for blogging. However, MMD is buggy and unstable – different versions of MMD generate different HTML. RST is very verbose and not featureful (e.g. column alignment in tables is missing). So, it would be nice to recenter all my worklow within the Python ecosystem. Enter python-markdown and its extensions pymdown-extensions. The latter brings support for maths rendering via KaTeX or MathJax.

The downsides being:

1. Inability to generate PDF but probably pandoc (or md2pdf) will digest this markdown anyway.
2. Slowness of Python compared to compiled exectuable like MMD. A few seconds for HTML generation for a personal blog is not a big deal.

Tables

Simple tables, as well as column alignments, are supported already:

markdown_py file.md -x extra -x meta

For the recent solar new year (nirayana mēṣa saṅkrānti), here are the dates for Ujjain, following the “sunset rule”:

Complex grid tables (e.g. multiple lines in a cell, cell merging and splitting, etc.) are supported by extensions like this one and this one. They can be plugged-in by the usual -x option to the markdown_py script like above.

Code syntax highlighting

Here is some example Python code:

def print_fruits():
  """
  This function lists some fruits.
  """
  fruits = ["apple", "banana", "cherry"]

  for fruit in fruits:
    print(fruit)

  return len(fruits)

The above is rendered by using the codehilite extension:

markdown_py -x extra -x meta -x codehilite -x smarty

There are may syntax coloring “themes”, I’ve used Emacs-style for this example:

pygmentize -S emacs -f html -a .code > emacs-style.css

Mathematics with KaTeX

The usual case is \(e^{j \pi} + j^2 + 2 = 0\), using single $ for in-line math and double dollars $$ (or \begin{}...\end{} blocks) for display math (block math). KaTeX rendering is supported via pymdownx.arithmatex.

This block:

\begin{aligned}
  a &= (x + y)^2         &  b &= (x - y)^2 \\
    &= x^2 + 2xy + y^2   &    &= x^2 - 2xy + y^2
\end{aligned}

will be rendered as:

Invocation is rather simple:

markdown_py -x extra -x meta -x codehilite -x smarty -x pymdownx.arithmatex -c arithmatex.json

The json file instructs arithmatex to use “generic” rendering so that KaTeX can be used:

{
  "pymdownx.arithmatex":
  {
    "generic": "True"
  }
}

See Arithmatex documentation above for more detail.