markdown-mote.nvim

Promote/demote Markdown headings and list items using Treesitter.

Requirements

• Neovim with nvim-treesitter
• markdown parser installed (:TSInstall markdown)

Check health with:

:checkhealth markdown-mote

Setup

require("markdown-mote").setup()

Installation

vim.pack

vim.pack.add({
  src = "https://github.com/albertoCaroM/markdown-mote.nvim",
})

lazy.nvim

{ "albertoCaroM/markdown-mote.nvim" }

packer.nvim

use("albertoCaroM/markdown-mote.nvim")

API

require("markdown-mote").setup()
require("markdown-mote").promote()
require("markdown-mote").demote()

Quickstart (Example Keymaps)

markdown-mote.nvim does not define keymaps by default. The mappings below are examples you can change to any keys you prefer.

Recommended setup in after/ftplugin/markdown.lua:

local mote = require("markdown-mote")

vim.keymap.set("n", "<Tab>", mote.demote, { buffer = true })
vim.keymap.set("n", "<S-Tab>", mote.promote, { buffer = true })
vim.keymap.set("v", "<Tab>", mote.demote, { buffer = true })
vim.keymap.set("v", "<S-Tab>", mote.promote, { buffer = true })

vim.api.nvim_buf_create_user_command(0, "MarkdownPromote", mote.promote, {})
vim.api.nvim_buf_create_user_command(0, "MarkdownDemote", mote.demote, {})

Available in Markdown buffers:

• :MarkdownPromote
• :MarkdownDemote

If you prefer defining this from init.lua, use a FileType autocmd with vim.api.nvim_buf_create_user_command(args.buf, ...) so commands stay Markdown-local.

Examples

Heading subtree demote (with the example <Tab> mapping on ## Parent):

## Parent
### Child

becomes:

### Parent
#### Child

List item promote (with the example <S-Tab> mapping on - child):

- item
  - child

becomes:

- item
- child

Behavior

• Headings: promote/demote the whole subtree (children included).
• Lists: indent/outdent the entire list item (children included).
• Visual mode: respects the selected range exactly.
• Limits: headings stay between levels 1 and 6.
• No-op: if no compatible node is found.
• Indentation: respects expandtab, shiftwidth, and tabstop.

Troubleshooting

• Parser missing: run :TSInstall markdown and re-open the file.
• No effect: ensure the buffer is filetype=markdown and Treesitter is enabled.

Tests

Run tests with the plenary harness:

nvim --headless -u tests/minimal_init.lua \
  -c "lua require('plenary.test_harness').test_directory('tests', { minimal_init = './tests/minimal_init.lua' })" \
  -c "qa"

Or use the Makefile helper:

make test

License

MIT. See LICENSE.