Markdown Title Numbering

A Neovim plugin for automatically numbering markdown titles.

1. Overview

This plugin automatically numbers markdown titles according to their hierarchy level, making it easy to maintain structured documents.

For detailed documentation, please see :help markdown-title-numbering after installation.

2. Quick Start

2.1 Installation

2.1.1 Using packer.nvim

use {
  'gitsang/markdown-title-numbering.nvim',
  config = function()
    require('markdown-title-numbering').setup({
      -- your configuration here (optional)
    })
  end
}

2.1.2 Using lazy.nvim

{
  'gitsang/markdown-title-numbering.nvim',
  ft = { 'markdown', 'mdx' },
  opts = {
    -- your configuration here (optional)
  }
}

2.2 Commands

• :MarkdownTitleNumber - Number all markdown titles in the current buffer
• :MarkdownTitleNumberRemove - Remove numbers from all markdown titles in the current buffer

Running :MarkdownTitleNumber will insert <!-- MarkdownTitleNumber --> at the first line (if missing). After that, titles are automatically renumbered on save for matching markdown files. Without this marker line at the beginning of the file, save will not modify titles.

2.3 Keybindings

{
  'gitsang/markdown-title-numbering.nvim',
  ft = { 'markdown', 'mdx' },
  opts = {},
  keys = {
    { '<leader>mtn', ':MarkdownTitleNumber<CR>', desc = 'Number markdown titles' },
    { '<leader>mtr', ':MarkdownTitleNumberRemove<CR>', desc = 'Remove markdown title numbers' },
  }
}

ft ensures the plugin loads when opening markdown files, so commands are available immediately.

2.4 Configuration

{
  'gitsang/markdown-title-numbering.nvim',
  opts = {
    file_patterns = { "*.md", "*.mdx", "*.markdown" }, -- File patterns to apply
    format = {
      [2] = "%d. ", -- ## 1. Title
      [3] = "%d.%d ", -- ### 1.1 Title
      [4] = "%d.%d.%d ", -- #### 1.1.1 Title
      [5] = "%d.%d.%d.%d ", -- ##### 1.1.1.1 Title
      [6] = "%d.%d.%d.%d.%d ", -- ###### 1.1.1.1.1 Title
    },
  }
}

2.5 Example

Before:

# Main Title

## Introduction

### Background

After:

# Main Title

## 1. Introduction

### 1.1 Background

For complete documentation including configuration options and features, see :help markdown-title-numbering.