Markdown Headings and Titles

Markdown is a great way to format notes, blog posts, a diary, articles, forum posts or even dissertation chapters. There are many tools out there to convert Markdown into other formats like HTML, LaTeX, DOCX or BB-Code.

There is also agreement that a heading with # should be converted to a <h1> tag, a ## heading to <h2> and so on. Markdown has its roots in HTML, so it makes perfect sense. For LaTeX one has to specify whether # is supposed to be a \section or rather a \chapter.

What creates most friction for me is the handling of document titles. Markdown likely wasn't thought of as a whole-document markup language, but it is widely used like that. There are three dominant ways to specify the title of a document.

The first method uses YAML metadata and looks like this:

---
title: Example title
date: today
author: Me
---

This has the advantage that one can add an arbitrary amount of extra data, which some generators might use. My Nikola blog posts for instance have a category, tags and status field, Pandoc and LaTeX uses documentclass, mainfont and so on.

The second method is to use the leading heading as a title. This is how MkDocs and Sphinx work. Effectively this removes one level of headings to use, but I rarely use more than three anyway.

And then one can use the filename in order to derive the title. This is how Obisidan seems to do that. This then doesn't conflict with the YAML metadata, which is nice.

If one works with one tool, these differences are fine. But when one shares content between the tools, it becomes a bit cumbersome to take care of that. Especially since Markdown headings encode an absolute level, one has to remove or add # characters to every single heading. In reStructuredText the heading levels are inferred, therefore one can easily add or a remove a title, if it should be necessary. But reStructuredText has specified that a single top level heading is the title, so that isn't even necessary.