Mandaris Moore


Geometry picture by pixabay.

Previously, I had written about how I found a solution to my compulsion to make sure that the headers on my blog were on the write2 level here.

As with so many other things in life, there was an easier1 solution that was built into python-markdown.

When I had first explored this issue, I had looked at the HeaderID it was marked as being deprecated and to be used for adding anchors for headings. I didn't read the whole thing because it didn't seem it would fit my needs. I continued on and found my current solution.

But, the thought that there could be a better way kept on nagging me even though I was happy3 with how my site turned out.

As I was in the process of updating my Pelican Test Content, I went back to the python-markdown extensions page to make sure that I had covered most of the use cases. I noticed that it had a Table of Contents.

All about that base

The first thing that I found was that the extension allows me to set the base for headers fairly easily by setting a property in my pelicanconfig.py.

# Markdown options
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'markdown.extensions.toc': {'baselevel': '3', 'title': 'Table of Contents'},
    },
    'output_format': 'html5',
}

This eliminates the need for the additional plugin and as an added bonus allows me to have a table of contents for those really long posts that I never write.

Table of Pain

The html that is generated is hard to read. There are only a couple mild things that I don't really enjoy about this new solution.

Div-ided we stand on syntax

  • I'd love if this wasn't in a div and used either a nav or aside tag for accessibility and my own personal comfort.
  • Also, the number of li and ul tags can be hard to read if you want to read the raw html.
  • Titles for table of contents is in a span tag. I find that kind of ironic.

Seriously, just nitpicky at this point.

Making it look nice

This part is just me going back to trying to figure out how to make it look nice in the browser. I imagine that it won't take long, but there are going to be a couple of ugly iterations.


  1. Easier being defined as having less dependencies. 

  2. Get it? :P 

  3. Mostly happy.