101

I'm trying to produce html with section / subsection headings resembling the following:

  1. My top-level topic
    1.1 My first subtopic
    1.2 Another subtopic
          1.2.1 A sub-subtopic
  2. Another top-level topic

Are there any implementations of Markdown capable of producing these kinds of numbered section headings?

starball
  • 20,030
  • 7
  • 43
  • 238
sterling938
  • 1,015
  • 2
  • 7
  • 7

5 Answers5

72

Yes, try Pandoc. This works for me:

pandoc --number-sections < test.md > out.html

(Source)

Markdown to produce the numbered outline you mention in the original post looks like this:

# My top-level topic

## My first subtopic

## Another subtopic

### A sub-subtopic

## Another top-level topic

If you want deeper indenting for sub-sections, you might be able to achieve this with inline CSS. For example, placing this at the top of the above Markdown source indents the headers:

<style type="text/css">
  h2 { margin-left: 10px; }
  h3 { margin-left: 20px; }
</style>

But say you had paragraphs of text under your headings... I don't know how to indent that to the same level as the above header.

Update 2015-10-18: Markdeep has numbered headings (and many other fancy features). Check that out too!

Konstantin Spirin
  • 20,609
  • 15
  • 72
  • 90
Adam Monsen
  • 9,054
  • 6
  • 53
  • 82
41

If your markdown tool supports customized theme by CSS, add below snippet into CSS to enable heading number:

body {
    counter-reset: h1
}

h1 {
    counter-reset: h2
}

h2 {
    counter-reset: h3
}

h3 {
    counter-reset: h4
}

h1:before {
    counter-increment: h1;
    content: counter(h1) ". "
}

h2:before {
    counter-increment: h2;
    content: counter(h1) "." counter(h2) ". "
}

h3:before {
    counter-increment: h3;
    content: counter(h1) "." counter(h2) "." counter(h3) ". "
}

h4:before {
    counter-increment: h4;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) ". "
}

I use Typora, which supports auto numbering for headings in this approach.

Konstantin Spirin
  • 20,609
  • 15
  • 72
  • 90
aleung
  • 9,848
  • 3
  • 55
  • 69
  • Well, this works for atom, if anyone is interested: change the first entry to `h1 { counter-increment: h1 }`, then comment out `counter-increment: h1` in `h1:before`. I don't understand why... – Alex Jan 22 '18 at 07:21
  • 2
    This should be selected as a general solution. It works for typora, multimarkdown and pandoc. –  Nov 23 '18 at 01:01
  • This should be the accepted solution as it's really generic. – Imad Oct 26 '22 at 15:40
12

If you want to edit the markdown file itself, and not only the resulting HTML file, try enumerate-markdown with python 3

pip install enumerate-markdown
markdown-enum filename.md 1 filename.md

Example - input

# header 1
text
## header 2
text
# header 3
text

Output

# 1.  header 1
text
## 1.1  header 2
text
# 2.  header 3
text

if you later edit the file and run the script again, then it updates old enumeration.

Jeromino
  • 171
  • 2
  • 3
  • 1
    Well, that's a curveball (`markdown-enum` as the command vs. `enumerate-markdown` as the package name). Was exactly what I was seeking, though! – ijoseph May 10 '20 at 18:21
  • I had to use markdown-enum filename.md filename.md for this to work. Eg markdown-enum filename.md 2 filename.md, which skips numbering the first level. – JohnShape Jun 29 '21 at 09:03
2

As @adam-monsen points out 'pandoc --number-sections' does the trick. You can also simply add numbersections: true to th YAML-Header to activate numbered headings for your file.

Jeremy
  • 328
  • 1
  • 8
-2

Markdown is intended to be fast, light, and easy to work with and it fits that bill perfectly. For more complex formatting, good to consider an option other than markdown. Not a cop-out. Often, e.g. with Microsoft languages and tools for example, I would want to do "xyz" and then realize that in that world, you are, by design, steered away from "xyz", to the preferred/supported means of accomplishing your goals.

For a specific example, consider vscode. People ask about toolbar/customization. Vscode isn't toolbar-centric. This is by design. The design intention is to use the command palette Ctrl+Shift+P. Saves time by not having to constantly be customizing your toolbar and it provides fast access to all commands, as opposed to only a subset of commands on the toolbar.