Skip to content

9.v2.0 Migration Guide

yousefhadder edited this page Mar 8, 2026 · 1 revision

v2.0 Migration Guide

This page covers everything you need to move from v1.x to v2.0.

Breaking Changes

  1. Explicit setup is required

    • vim.g.markdown_plus config support is removed.
    • Use require("markdown-plus").setup(opts) (or opts = {} in lazy.nvim).
  2. Default mappings moved to <localleader>

    • Replace old <leader> assumptions with <localleader>.
    • If needed, define your localleader explicitly before plugin setup:
vim.g.maplocalleader = "\\"
  1. Internal API change for integrations
    • headers.parse_header() now expects two args:
    • parse_header(line, next_line)

Keymap Migration (Common)

v1 key v2 key Note
<leader>... <localleader>... Prefix migration across defaults
<localleader>ms (strikethrough) <localleader>mS Uppercase S
<localleader>mc (inline code) `m`` Inline code moved
<localleader>mh (highlight) <localleader>m= Highlight moved
<localleader>mC (clear formatting) <localleader>mF Clear formatting moved
]c / [c (code-block nav) ]b / [b Avoids diff-mode conflict

Minimal v2 setup (lazy.nvim)

{
  "yousefhadder/markdown-plus.nvim",
  ft = "markdown",
  opts = {},
}

v2.0 Additions and Improvements

Phase 1 (breaking + keymap consistency)

  • Removed deprecated auto-setup path
  • Standardized default keymap behavior around <localleader>
  • Standardized <Plug> naming (including table keymaps)

Phase 2

  • Added HTML block awareness (features.html_block_awareness = true) so list/format/header operations skip raw HTML blocks

Phase 3

  • Added thematic break module (<localleader>mh, <localleader>mH)
  • Added smart parent-aware outdent (list.smart_outdent = true)
  • Added setext heading support and heading-style toggle (<localleader>ms)

Phase 4

  • Added escape-aware formatting detection and visual escape toggle (<localleader>me)
  • Added full code block module:
    • Insert/wrap: <localleader>mc
    • Change language: <localleader>mC
    • Navigate: ]b / [b

Review hardening and cleanup

  • Async-safe language picker flow for vim.ui.select
  • Consolidated code-fence parsing utilities
  • Extracted markdown escape helpers to dedicated format module

Upgrade Checklist

  • Remove any vim.g.markdown_plus config usage
  • Ensure plugin manager calls setup (opts = {} or explicit setup())
  • Update your custom keymaps from <leader> to <localleader>
  • Update overridden format/code-block mappings per table above
  • Run :checkhealth markdown-plus

Clone this wiki locally