is there a way to make the headings, sections and subsections numbering in markdown language?

Question

I would like to number the Headings, sections and subsections in markdown language. So that the TOC would look like below:

1. Heading1
2. Heading2
   2.1 Section1
   2.2 Section2
        2.2.1 Subsection1
        2.2.2 Subsection2

I am using MKDOCS to create my static web pages, apython package. Are there any markdown-extensions which can do that ?

Am new to using the markdown language, any help and suggestions are welcome.

Answer 1

The following uses react and styled-components:

To create a header numbering for markdown the represents the auto numbering in JupyterLab, you can use the following style:

import styled, { css } from 'styled-components'

/**
 * The index property is used to continually increment H1 headers
 * between sections / paragraphs
 * */
export type headerNumberingType = {
  display: boolean
  enableH1: boolean
  index: number
}

export const HeaderNumberingStyle = styled.div<{settings:headerNumberingType}>`
  ${(props) => props.settings.display && css`
    h1 { counter-reset: h1 h2 h3 h4 h5 h6 }
    h2 { counter-reset: h3 h4 h5 h6 }
    h3 { counter-reset: h4 h5 h6 }
    h4 { counter-reset: h5 h6 }
    h5 { counter-reset: h6 }
    h6 {  }
    
    ${props.settings.enableH1 && css `
      h1:before {
        counter-increment: h1 ${props.settings.index}; //increment by the index 
        content: counter(h1) ". ";
      }
    `}
    
    h2:before {
      counter-increment: h2;
      content: ${props.settings.enableH1
        ? css`counter(h1) "." counter(h2) ". ";`
        : css`counter(h2) ". "`      
      }
    }

    h3:before {
      counter-increment: h3;
      content: ${props.settings.enableH1
              ? css`counter(h1) "." counter(h2) "." counter(h3) ". ";`
              : css`counter(h2) "." counter(h3) ". "`
      }
    }

    h4:before {
      counter-increment: h4;
      content: ${props.settings.enableH1
              ? css`counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) ". ";`
              : css`counter(h2) "." counter(h3) "." counter(h4) ". "`
      }
    }

    h5:before {
      counter-increment: h5;
      content: ${props.settings.enableH1
              ? css`counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". ";`
              : css`counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "`
      }
    }

    h6:before {
      counter-increment: h6;
      content: ${props.settings.enableH1
              ? css`counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". ";`
              : css`counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "`
      }
    }
  `}
`

The important part of the style is:

h1 { counter-reset: h1 h2 h3 h4 h5 h6 }
    h2 { counter-reset: h3 h4 h5 h6 }
    h3 { counter-reset: h4 h5 h6 }
    h4 { counter-reset: h5 h6 }
    h5 { counter-reset: h6 }
    h6 {  }

This will reset header number if moving from a higher header (h3) to a lower header (h2)

The parameters passed in are for my business specs:

1. display => allow to display or hide header numbers
2. enableH1 => display / hide H1 header numbers
3. index => optional: will increment H1 between sections

To use in react:

import React from 'react'
import { HeaderNumberingStyle } from './MarkdownStyles'
const Home = () => {
  const sections:number[] = [1,2]
  const getSectionData = (index: number) => {
    switch (index){
      case 1:
        return (
          <div key={index * 1000}>
            <h1>Header 1</h1>
            <h6>Header 6</h6>
            <h2>Header 2</h2>
            <h4>Header 4 A</h4>
            <h4>Header 4 B</h4>
            <h2>Header 2 B</h2>
          </div>
        )
      case 2:
        return (
          <div key={2000}>
            <h1>Header 1 new section</h1>
          </div>

        )
    }
  }

  return (
    <div>
      { sections.map((i:number) => {
        return (
          <HeaderNumberingStyle key={i} settings={{ display: true, enableH1: true, index: i}}>
            <div key={i * 10}>
              { getSectionData(i)}
            </div>
          </HeaderNumberingStyle>
        )
      }) }
    </div>
  )
}

export default Home

Answer 2

The following Python based CLI tool enumerates headings in your markdown

https://github.com/a4vision/enumerate-markdown

It adds headings to a markdown file. For example:

Input

# header
text
## sub-header
# header

Output

# 1. header
text
## 1.2 sub-header
# 2. header

Answer 3

Numbering headers is not something that HTML can do, but there is standard way to do it with css.

In case you have not yet done it, add this declaration in the mkdocs.yml file:

extra_css: [specific.css]

Then write this in the specific.css file in the docsdirectory (this is the css code proposed, verbatim, so I let you check if it works for you):

body {
counter-reset : h2;
    }

h2 {
counter-reset : h3;
    }

h3 {
counter-reset : h4;
    }

h4 {
counter-reset : h5;
    }

h5 {
counter-reset : h6;
    }

article h2:before {
content : counter(h2,decimal) ". ";
counter-increment : h2;
    }

article h3:before {
content : counter(h2,decimal) "." counter(h3,decimal) ". ";
counter-increment : h3;
    }

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

article h5:before {
content : counter(h2,decimal) "." counter(h3,decimal) "." counter(h4,decimal) "." counter(h5,decimal) ". ";
counter-increment : h5;
    }

article h6:before {
content : counter(h2,decimal) "." counter(h3,decimal) "." counter(h4,decimal) "." counter(h5,decimal) "." counter(h6,decimal) ". ";
counter-increment : h6;
    }

h2.nocount:before, h3.nocount:before, h4.nocount:before, h5.nocount:before, h6.nocount:before {
content : "";
counter-increment : none;
    }