markdown-plus.txt

*markdown-plus.txt*      Enhanced Markdown editing for Neovim      Last change: 2025 January 19

==============================================================================
Table of Contents                            *markdown-plus-table-of-contents*

1. Introduction                                       |markdown-plus-introduction|
  - Features                                 |markdown-plus-introduction-features|
2. Installation                                       |markdown-plus-installation|
  - lazy.nvim                               |markdown-plus-installation-lazy.nvim|
  - Configuration                     |markdown-plus-installation-configuration|
3. Usage                                                     |markdown-plus-usage|
  - Headers                                        |markdown-plus-usage-headers|
  - Lists                                            |markdown-plus-usage-lists|
  - Formatting                                  |markdown-plus-usage-formatting|
  - Links                                            |markdown-plus-usage-links|
  - Quotes                                          |markdown-plus-usage-quotes|
  - Tables                                          |markdown-plus-usage-tables|
4. Configuration                                     |markdown-plus-configuration|
  - Keymaps                                  |markdown-plus-configuration-keymaps|
  - Options                                  |markdown-plus-configuration-options|
5. Commands                                               |markdown-plus-commands|
6. API                                                         |markdown-plus-api|
7. Troubleshooting                                 |markdown-plus-troubleshooting|
8. Contributing                                       |markdown-plus-contributing|
9. License                                                 |markdown-plus-license|

==============================================================================
1. Introduction                                       *markdown-plus-introduction*

markdown-plus.nvim is a comprehensive plugin that enhances Markdown editing in
Neovim with intelligent formatting, list management, header manipulation, and
table of contents generation. It provides context-aware keymaps that work
seamlessly within lists while preserving normal Vim behavior elsewhere.

The plugin is designed to be lightweight, fast, and integrate naturally with
your existing Neovim workflow.

Note: While originally designed for Markdown, this plugin can be configured to
work with any filetype. See |markdown-plus-configuration-filetypes| for details.


FEATURES                                     *markdown-plus-introduction-features*

- Smart list management:
  - Auto-continuation with proper markers and indentation
  - Intelligent renumbering for ordered and letter-based lists
  - Support for multiple list types (unordered, ordered, letter-based, parenthesized)
  - Context-aware Tab/Shift-Tab for indentation
  - Automatic empty item removal
  - Smart backspace to remove list markers

- Header operations:
  - Quick header level promotion/demotion
  - Set specific header levels (H1-H4)
  - Navigate between headers with ]] and [[
  - Generate and update Table of Contents (TOC) with GitHub-style anchors
  - TOC duplicate prevention with HTML comment markers
  - Navigate to headers from TOC

- Text formatting:
  - Toggle bold, italic, strikethrough, and inline code
  - Convert selected rows to code block
  - Smart formatting that respects word boundaries
  - Clear all formatting from selected text
  - Works in both normal and visual mode

- Links & References:
  - Insert and edit markdown links
  - Convert text selection to links
  - Auto-convert bare URLs to markdown links
  - Convert between inline and reference-style links
  - Smart reference ID generation and reuse
  - Open links with native Neovim (gx)

- Quotes Management:
  - Toggle blockquote on current line or visual selection

- Table Support (Phase 1):
  - Create tables interactively with custom dimensions
  - Auto-format and align table columns
  - Normalize malformed tables
  - Row operations (insert, delete, duplicate)
  - Column operations (insert, delete, duplicate)
  - Insert mode navigation with Alt+hjkl (circular wrapping)
  - Alignment support (left, center, right)
  - Smart cursor positioning after operations

- Context-aware keymaps:
  - List operations only active within lists
  - Proper fallback to default Vim behavior
  - Insert mode operations that respect context


==============================================================================
2. Installation                                       *markdown-plus-installation*


LAZY.NVIM                                   *markdown-plus-installation-lazy.nvim*

Basic installation for markdown files:
>lua
    {
      'yousefhadder/markdown-plus.nvim',
      ft = 'markdown',
      opts = {
        -- See configuration section for available options
      },
    }
<

Installation for multiple filetypes:
>lua
    {
      'yousefhadder/markdown-plus.nvim',
      ft = { 'markdown', 'text', 'txt' },
      config = function()
        require('markdown-plus').setup({
          filetypes = { 'markdown', 'text', 'txt' },
        })
      end,
    }
<


CONFIGURATION                         *markdown-plus-installation-configuration*

Basic configuration with custom keymaps:

>lua
    {
      'yousefhadder/markdown-plus.nvim',
      ft = 'markdown',
      config = function()
        require('markdown-plus').setup({
          enabled = true,
          features = {
            list_management = true,
            text_formatting = true,
            headers_toc = true,
            links = true,
            quotes = true,
            code_block = true,
            table = true,
          },
        })
      end,
    }
<


==============================================================================
3. Usage                                                     *markdown-plus-usage*


HEADERS                                            *markdown-plus-usage-headers*

Headers are lines starting with one or more `#` symbols.


PROMOTE/DEMOTE ~

Place your cursor on a header line and use:
- `<leader>h+` to promote (decrease level, add `#`)
- `<leader>h-` to demote (increase level, remove `#`)

Example:
>
    ### Header              ->   ## Header     (promoted with <leader>h+)
    ## Another Header       ->   ### Another   (demoted with <leader>h-)
<

You can also set a specific header level directly:
- `<leader>h1` to convert to H1 (# Header)
- `<leader>h2` to convert to H2 (## Header)
- `<leader>h3` to convert to H3 (### Header)
- `<leader>h4` to convert to H4 (#### Header)
- `<leader>h5` to convert to H5 (##### Header)
- `<leader>h6` to convert to H6 (###### Header)


NAVIGATE HEADERS ~

Jump between headers quickly:
- `]]` to jump to next header
- `[[` to jump to previous header



TABLE OF CONTENTS ~

Generate a TOC with `<leader>ht`. The TOC will be wrapped in HTML comment
markers to prevent duplicates:

>markdown
    <!-- TOC -->

    ## Table of Contents

    - [Introduction](#introduction)
    - [Getting Started](#getting-started)
      - [Installation](#installation)
      - [Configuration](#configuration)

    <!-- /TOC -->
<

The HTML markers (`<!-- TOC -->` and `<!-- /TOC -->`) are invisible in
rendered Markdown but provide clear boundaries. If you try to generate a TOC
when one already exists, you'll see: "TOC already exists. Use <leader>hu to
update it."

Update the TOC with `<leader>hu` when you've added or modified headers.

Follow TOC links with `gd` when cursor is on a link to jump to that header.

TOC WINDOW (NAVIGABLE) ~
                                                    *markdown-plus-toc-window*

Open an interactive Table of Contents window to browse and navigate your
document structure:

>vim
    :Toc          " Open TOC in vertical split
    :Toch         " Open TOC in horizontal split
    :Toct         " Open TOC in new tab
    <leader>hT    " Default keymap to toggle TOC
<

Features:
    - Progressive disclosure: Shows H1-H2 initially, expand on demand
    - Fold/unfold: `l` to expand, `h` to collapse or jump to parent
    - Color-coded levels: Each header level has distinct color
    - Visual markers: ▶ (collapsed), ▼ (expanded)
    - Jump to headers: Press <Enter> on any header
    - Help popup: Press ? for keyboard shortcuts
    - Toggle on/off: No duplicate windows
    - Auto-sizing: Window adapts to content width

Keymaps (inside TOC):
    l           Expand header to show children
    h           Collapse header or jump to parent
    <Enter>     Jump to header in source buffer
    q           Close TOC window
    ?           Show help popup

Configuration:
    initial_depth: Set initial display depth (default: 2)
>lua
    require('markdown-plus').setup({
      toc = {
        initial_depth = 3,  -- Show H1-H3 initially
      }
    })
<


LISTS                                                *markdown-plus-usage-lists*

markdown-plus.nvim provides intelligent list management with context-aware
behavior for multiple list types:

  - Unordered: `-`, `*`, `+`
  - Ordered: `1.`, `2.`, `3.`
  - Letter-based: `a.`, `b.`, `c.` and `A.`, `B.`, `C.`
  - Parenthesized: `1)`, `2)` and `a)`, `b)` and `A)`, `B)`

All list types support checkboxes (e.g., `- [ ]`, `1. [x]`, `a. [ ]`).

CHECKBOX TOGGLING ~

Toggle checkboxes with `<leader>mx` in normal/visual mode or `<C-t>` in insert
mode:

>markdown
    - Regular item         Press <leader>mx    →  - [ ] Regular item
    - [ ] Unchecked        Press <leader>mx    →  - [x] Unchecked
    - [x] Checked          Press <leader>mx    →  - [ ] Checked

    Works with all list types:
    1. Item                →  1. [ ] Item       →  1. [x] Item
    a. Task                →  a. [ ] Task       →  a. [x] Task

    Visual mode - select lines and press <leader>mx to toggle multiple items
    Insert mode - press <C-t> to toggle without leaving insert mode
<

AUTO-CONTINUATION ~

Press `<CR>` in insert mode or `o`/`O` in normal mode on a list item to
create a new item:

>markdown
    - First item
    - Second item|         ->    - Second item
                                 - |

    1. First item
    2. Second item|        ->    2. Second item
                                 3. |

    a. First letter
    b. Second letter|      ->    b. Second letter
                                 c. |
<

Empty items are automatically removed when you press `<CR>` again:

>markdown
    - Item one
    - |                    ->    - Item one

                                 |
<

Note: In insert mode, `<CR>` is context-aware - it only creates new list
items when you're actually in a list. Outside of lists, it behaves normally.


INDENTATION ~

Use `<Tab>` and `<S-Tab>` in insert mode to indent/dedent list items.
All list types maintain their marker style when indented:

>markdown
    - Item
      - Sub-item|          <Tab>    - Item
      - Another                       - Sub-item
                                        - |
                                      - Another
<

Outside of lists, `<Tab>` and `<S-Tab>` insert/remove indentation normally.


RENUMBERING ~

Ordered and letter-based lists are automatically renumbered as you edit.
Manual renumbering is available with `<leader>mr`.

The renumbering system intelligently handles:
- Nested lists: Each nesting level maintains independent numbering
- Blank lines: Lists separated by blank lines restart numbering from 1/a/A
- Mixed depths: Works correctly at any nesting depth

Example of nested list renumbering:
>markdown
    1. A
        1. B
        2. C
    2. D
        1. E    <- Correctly restarts at 1 (not 3)
        2. F
<

Example of blank line separation:
>markdown
    1. First list
    2. Second item

    1. New list    <- Restarts at 1 after blank line
    2. Second item
<


SMART BACKSPACE ~

The `<BS>` key in insert mode is context-aware:
- In empty list items: removes the list marker
- Otherwise: deletes character normally


FORMATTING                                      *markdown-plus-usage-formatting*

All formatting commands work in both normal and visual mode. Use `<leader>m`
prefix for formatting operations.


BOLD ~

Toggle bold with `<leader>mb`:

>markdown
    This is text           ->    This is *bold text*
    This is *bold text*    ->    This is text
<


ITALIC ~

Toggle italic with `<leader>mi`:

>markdown
    This is text           ->    This is *italic text*
    This is *italic text*  ->    This is text
<


STRIKETHROUGH ~

Toggle strikethrough with `<leader>ms`:

>markdown
    This is text           ->    This is ~~text~~
    This is ~~text~~       ->    This is text
<


CODE ~

Toggle inline code with `<leader>mc`:

>markdown
    This is code           ->    This is `code`
    This is `code`         ->    This is code
<
CODE BLOCK ~

Convert selected rows to a code block with `<leader>mw`:
1. Enter visual block mode with `V`.
2. Select the rows you want to convert.
3. Press `<leader>mw`.
4. Enter the language for the code block when prompted (e.g., txt).

>markdown
    This is some text
    and more text
<

After following the steps above, the selected text will become:

>markdown
    ```txt
    This is some text
    and more text
    ```
<

CLEAR FORMATTING ~

Remove all formatting with `<leader>mC`:

>markdown
    Formatted text         ->    This is some text
<


LINKS                                                *markdown-plus-usage-links*

markdown-plus.nvim provides comprehensive link management with support for
both inline and reference-style links.


INSERT NEW LINK ~

Press `<leader>ml` in normal mode to insert a new link:

>markdown
    Cursor here|          ->    [GitHub](https://github.com)|
<

You'll be prompted for:
1. Link text (e.g., "GitHub")
2. URL (e.g., "https://github.com")


CONVERT SELECTION TO LINK ~

Select text in visual mode and press `<leader>ml`:

>markdown
    Visit my website      ->    Visit [my website](https://example.com)
          ^^^^^^^^^^
          (selected)
<

You'll be prompted for the URL only.


EDIT EXISTING LINK ~

Place cursor anywhere on a link and press `<leader>me`:

>markdown
    [Old Text](https://old-url.com)

    Press <leader>me:
    1. Link text: Old Text (edit or press Enter)
    2. URL: https://old-url.com (edit or press Enter)

    Result: [New Text](https://new-url.com)
<

Works with both inline links `[text](url)` and reference links `[text][ref]`.


OPEN LINKS IN BROWSER ~

Use Neovim's native `gx` command to open links:

>markdown
    [Google](https://google.com)     <- Press gx here
    https://example.com              <- Also works on bare URLs
<

The `gx` command will open the URL in your default browser.


AUTO-CONVERT URL TO LINK ~

Place cursor on a bare URL and press `<leader>ma`:

>markdown
    https://github.com/user/repo

    Press <leader>ma:
    Link text (empty for URL): GitHub Repo

    Result: [GitHub Repo](https://github.com/user/repo)
<

Leave the text prompt empty to use the URL as link text.


REFERENCE-STYLE LINKS ~

Convert inline link to reference-style with `<leader>mR`:

>markdown
    [Documentation](https://docs.example.com)

    Press <leader>mR:

    Result:
    [Documentation][documentation]

    ... (at end of document)
    [documentation]: https://docs.example.com
<

The reference ID is auto-generated from the link text (lowercase, hyphens,
alphanumeric only).

Convert reference link to inline with `<leader>mI`:

>markdown
    [My Link][myref]

    [myref]: https://myref.com

    Press <leader>mI on the link:

    Result: [My Link](https://myref.com)
<


REFERENCE REUSE ~

When converting links with the same text and URL to reference-style, the
plugin automatically reuses the existing reference:

>markdown
    Check out [GitHub](https://github.com) for code.
    Visit [GitHub](https://github.com) to see projects.

    Press <leader>mR on both:

    Result:
    Check out [GitHub][github] for code.
    Visit [GitHub][github] to see projects.

    [github]: https://github.com  <- Only one definition
<

Links with different text create separate references even with same URL:

>markdown
    [dotfiles](https://github.com/yousefhadder/dotfiles)
    [My Dotfiles](https://github.com/yousefhadder/dotfiles)

    Press <leader>mR on both:

    Result:
    [dotfiles][dotfiles]
    [My Dotfiles][my-dotfiles]

    [dotfiles]: https://github.com/yousefhadder/dotfiles
    [my-dotfiles]: https://github.com/yousefhadder/dotfiles
<
QUOTES                                            *markdown-plus-usage-quotes*

Toggle blockquote on current line or visual selection with `<leader>mq`.

NORMAL MODE ~

Place cursor on a line and press `<leader>mq`:
>markdown
    This is a normal line -> > This is a normal line
    > This is a quoted line -> This is a normal line
<
VISUAL MODE ~

Select multiple lines in visual mode and press `<leader>mq`:
>markdown
    Normal line 1
    Normal line 2
    ->
    > Normal line 1
    > Normal line 2
<


TABLES                                            *markdown-plus-usage-tables*

Table support provides comprehensive features for creating, formatting, and
manipulating markdown tables.


CREATE TABLES ~

Create a new table interactively with `<leader>tc`. You'll be prompted for:
1. Number of rows (excluding header)
2. Number of columns

Example result:
>markdown
    | Header 1 | Header 2 | Header 3 |
    |----------|----------|----------|
    |          |          |          |
    |          |          |          |
<

FORMAT AND NORMALIZE ~

Format tables with `<leader>tf` to auto-align columns:
>markdown
    | Name | Age | City |          | Name  | Age | City |
    |---|---|---|            ->     |-------|-----|------|
    | Alice | 25 | NYC |            | Alice | 25  | NYC  |
    | Bob | 30 | LA |               | Bob   | 30  | LA   |
<

Normalize malformed tables with `<leader>tn`:
>markdown
    | Header 1 | Header 2          | Header 1 | Header 2 |
    |---|---                  ->    |----------|----------|
    Missing | pipes                 | Missing  | pipes    |
<

ROW OPERATIONS ~

Insert rows:
- `<leader>tir` - Insert row below current row
- `<leader>tiR` - Insert row above current row

Delete rows:
- `<leader>tdr` - Delete current row (protects header/separator)

Duplicate rows:
- `<leader>tyr` - Duplicate current row below

Example:
>markdown
    | Name  | Age |
    |-------|-----|
    | Alice | 25  |  <- Press <leader>tir
    | Bob   | 30  |

    Result:
    | Name  | Age |
    |-------|-----|
    | Alice | 25  |
    |       |     |  <- New empty row
    | Bob   | 30  |
<

COLUMN OPERATIONS ~

Insert columns:
- `<leader>tic` - Insert column to the right
- `<leader>tiC` - Insert column to the left

Delete columns:
- `<leader>tdc` - Delete current column (protects last column)

Duplicate columns:
- `<leader>tyc` - Duplicate current column to the right

Example:
>markdown
    | Name  | Age |         | Name  | Age |     |
    |-------|-----|   ->    |-------|-----|-----|
    | Alice | 25  |         | Alice | 25  |     |
           ^ <leader>tic pressed here
<

ALIGNMENT SUPPORT ~

Tables support three alignment types in separator row:
- Left-aligned (default): `:---`
- Center-aligned: `:---:`
- Right-aligned: `---:`

Example:
>markdown
    | Left | Center | Right |
    |:-----|:------:|------:|
    | A    |   B    |     C |
    | D    |   E    |     F |
<

Formatting operations preserve alignment markers.


INSERT MODE NAVIGATION ~

Navigate table cells in insert mode using Alt+hjkl:
- `<A-h>` - Move to cell on the left
- `<A-l>` - Move to cell on the right
- `<A-j>` - Move to cell below
- `<A-k>` - Move to cell above

Navigation wraps around (circular):
- Moving right at last column wraps to first column
- Moving left at first column wraps to last column
- Moving down at last row wraps to header row
- Moving up at header row wraps to last data row

Example:
>markdown
    | Name  | Age | City     |
    |-------|-----|----------|
    | Alice | 25  | New York |  <- cursor here
    | Bob   | 30  | LA       |

    Press <A-l> to move right:
    | Name  | Age | City     |
    |-------|-----|----------|
    | Alice | 25  | New York |
    | Bob   | 30  | LA       |  <- cursor moves here
                    ^
<

When not in a table, navigation keys fall back to arrow keys.


TABLE FEATURES ~

Smart cursor positioning:
  After all operations, cursor is automatically positioned in the most
  logical cell (first cell of new/modified row/column).

Header protection:
  Cannot delete header row or separator row. Operations maintain table
  structure integrity.

Minimum constraints:
  - Cannot delete the last column
  - Cannot delete the only data row
  - Always maintains: header + separator + at least one data row


==============================================================================
4. Configuration                                     *markdown-plus-configuration*


KEYMAPS                                      *markdown-plus-configuration-keymaps*

Keymaps are automatically set up when the plugin loads (for configured filetypes).
You can disable all defaults with `keymaps.enabled = false` and use provided
`<Plug>` mappings to define custom keymaps (see below).

Default keymaps:

>lua
    {
      keymaps = {
        -- Header operations
        promote_header = '<leader>h+',      -- Promote (increase level)
        demote_header = '<leader>h-',       -- Demote (decrease level)
        generate_toc = '<leader>ht',        -- Generate TOC
        update_toc = '<leader>hu',          -- Update TOC
        open_toc_window = '<leader>hT',     -- Toggle TOC window
        next_header = ']]',                 -- Jump to next header
        prev_header = '[[',                 -- Jump to previous header
        set_h1 = '<leader>h1',              -- Convert to H1
        set_h2 = '<leader>h2',              -- Convert to H2
        set_h3 = '<leader>h3',              -- Convert to H3
        set_h4 = '<leader>h4',              -- Convert to H4
        set_h5 = '<leader>h5',              -- Convert to H5
        set_h6 = '<leader>h6',              -- Convert to H6

        -- List operations (Insert mode)
        auto_continue = '<CR>',             -- Auto-continue lists or split content
        continue_content = '<A-CR>',        -- Continue content on next line
        indent_list = '<Tab>',              -- Indent list item
        dedent_list = '<S-Tab>',            -- Dedent list item
        smart_backspace = '<BS>',           -- Smart backspace

        -- List operations (Normal mode)
        new_item_below = 'o',               -- New list item below
        new_item_above = 'O',               -- New list item above
        renumber_lists = '<leader>mr',      -- Manual renumber
        toggle_checkbox = '<leader>mx',     -- Toggle checkbox (normal/visual)
        debug_lists = '<leader>md',         -- Debug: show list groups

        -- List operations (Insert mode - checkbox)
        toggle_checkbox_insert = '<C-t>',   -- Toggle checkbox in insert mode

        -- Formatting operations (normal + visual)
        toggle_bold = '<leader>mb',
        toggle_italic = '<leader>mi',
        toggle_strikethrough = '<leader>ms',
        toggle_code = '<leader>mc',
        convert_to_code_block = '<leader>mw', -- Convert selection to code block
        clear_formatting = '<leader>mC',

        -- Link operations
        insert_link = '<leader>ml',        -- Insert/convert to link
        edit_link = '<leader>me',          -- Edit link under cursor
        auto_link_url = '<leader>ma',      -- Convert URL to link
        to_reference = '<leader>mR',       -- Convert to reference-style
        to_inline = '<leader>mI',          -- Convert to inline
        follow_link = 'gd',                -- Follow TOC link
        open_link = 'gx',                  -- Open link in browser (native)

        -- Quotes operations
        toggle_quote = '<leader>mq',       -- Toggle blockquote

        -- Table operations (Normal mode)
        table_create = '<leader>tc',       -- Create table interactively
        table_format = '<leader>tf',       -- Format table
        table_normalize = '<leader>tn',    -- Normalize malformed table
        table_insert_row_below = '<leader>tir',    -- Insert row below
        table_insert_row_above = '<leader>tiR',    -- Insert row above
        table_delete_row = '<leader>tdr',          -- Delete current row
        table_duplicate_row = '<leader>tyr',       -- Duplicate current row
        table_insert_column_right = '<leader>tic', -- Insert column right
        table_insert_column_left = '<leader>tiC',  -- Insert column left
        table_delete_column = '<leader>tdc',       -- Delete current column
        table_duplicate_column = '<leader>tyc',    -- Duplicate current column
        table_toggle_alignment = '<leader>ta',     -- Toggle cell alignment
        table_clear_cell = '<leader>tx',           -- Clear cell content
        table_move_column_left = '<leader>tmh',    -- Move column left
        table_move_column_right = '<leader>tml',   -- Move column right
        table_move_row_up = '<leader>tmk',         -- Move row up
        table_move_row_down = '<leader>tmj',       -- Move row down
        table_transpose = '<leader>tt',            -- Transpose table
        table_sort_ascending = '<leader>tsa',      -- Sort by column (ascending)
        table_sort_descending = '<leader>tsd',     -- Sort by column (descending)
        table_to_csv = '<leader>tvx',              -- Convert table to CSV
        csv_to_table = '<leader>tvi',              -- Convert CSV to table

        -- Table operations (Insert mode)
        table_move_left = '<A-h>',         -- Move to cell left (wraps)
        table_move_right = '<A-l>',        -- Move to cell right (wraps)
        table_move_down = '<A-j>',         -- Move to cell down (wraps)
        table_move_up = '<A-k>',           -- Move to cell up (wraps)
      }
    }
<


OPTIONS                                      *markdown-plus-configuration-options*

The plugin can be configured through the setup function:

>lua
    require('markdown-plus').setup({
      enabled = true,           -- Enable/disable the plugin
      features = {
        list_management = true,  -- List auto-continuation, indentation, etc.
        table = true,            -- Table support features
        text_formatting = true,  -- Bold, italic, strikethrough, code
        headers_toc = true,      -- Header manipulation and TOC generation
        links = true,            -- Link management and references
        quotes = true,           -- Blockquote (>) management
        code_block = true,       -- Convert selected text to code blocks
      },
      toc = {                    -- TOC window configuration
        initial_depth = 2,
      },
      table = {                  -- Table sub-configuration
        auto_format = true,
        default_alignment = 'left', -- 'left' | 'center' | 'right'
        confirm_destructive = true,  -- Confirm before transpose/sort operations
        keymaps = {
          enabled = true,
          prefix = '<leader>t',
          insert_mode_navigation = true,  -- Alt+hjkl navigation in insert mode
        },
      },
      keymaps = {
        enabled = true,          -- Enable/disable default keymaps
      },
      filetypes = { 'markdown' }, -- Filetypes to enable the plugin for
    })
<

Alternative: vim.g Configuration           *markdown-plus-configuration-vim-g*

For Vimscript compatibility or if you prefer not to call setup(), you can
configure the plugin using |vim.g.markdown_plus|:

Using a table (Lua): ~
>lua?
    vim.g.markdown_plus = {
      enabled = true,
      features = {
        list_management = true,
        text_formatting = false,
        quotes = true,
      },
      keymaps = {
        enabled = false,
      },
      filetypes = { 'markdown', 'text' },
    }
<

Using a table (Vimscript): ~
>vim
    let g:markdown_plus = #{
      \ enabled: v:true,
      \ features: #{
      \   list_management: v:true,
      \   text_formatting: v:false,
      \   quotes: v:true
      \ },
      \ keymaps: #{
      \   enabled: v:false
      \ },
      \ filetypes: ['markdown', 'text']
      \ }
<

Using a function (dynamic configuration): ~
>lua
    vim.g.markdown_plus = function()
      return {
        enabled = vim.fn.has('nvim-0.10') == 1,
        features = {
          text_formatting = not vim.g.vscode,  -- Disable in VSCode
          quotes = true,
        },
      }
    end
<

Configuration Priority ~

When both |vim.g.markdown_plus| and setup() are used, they are merged with
the following priority:

  1. Default configuration (lowest priority)
  2. vim.g.markdown_plus configuration
  3. setup(opts) parameter (highest priority)

Example:
>lua
    vim.g.markdown_plus = {
      features = { list_management = false },
    }
    
    require('markdown-plus').setup({
      features = { list_management = true },  -- Overrides vim.g
    })
    -- Result: list_management will be true
<

This allows you to set global defaults with vim.g and override specific
settings with setup() for certain filetypes or conditions.

                                        *markdown-plus-configuration-filetypes*

The plugin can be enabled for any filetype, not just markdown. This is useful
for plain text files, note-taking formats, or any text-based format where you
want markdown-style formatting.

Example: Enable for markdown and plain text files ~
>lua
    require('markdown-plus').setup({
      filetypes = { 'markdown', 'text', 'txt' },
    })
<

Example: Enable for custom note-taking setup ~
>lua
    require('markdown-plus').setup({
      filetypes = { 'markdown', 'note', 'org', 'wiki' },
    })
<

Important: Make sure your plugin manager also loads the plugin for these
filetypes. For lazy.nvim:
>lua
    {
      'yousefhadder/markdown-plus.nvim',
      ft = { 'markdown', 'text', 'txt' },  -- Match your filetypes config
      config = function()
        require('markdown-plus').setup({
          filetypes = { 'markdown', 'text', 'txt' },
        })
      end,
    }
<

Future versions may add:
- Table manipulation features
- Code block management
- Custom TOC formatting options
- Custom list markers
- Custom header anchor generation
- Keymap customization
- Link following behavior customization


==============================================================================
5. Commands                                               *markdown-plus-commands*

                                                                          *:Toc*
:Toc            Open Table of Contents in vertical split window.
                Toggles the TOC window: if open, closes it; if closed, opens
                it in a vertical split.

                Note: All TOC commands (:Toc, :Toch, :Toct) share the same
                toggle state. If the TOC window is open (regardless of layout),
                running any TOC command will close it. To change the layout,
                close the TOC window first, then run the desired command.

                                                                         *:Toch*
:Toch           Open Table of Contents in horizontal split window.
                See note above regarding toggle behavior.

                                                                         *:Toct*
:Toct           Open Table of Contents in new tab.
                See note above regarding toggle behavior.

These commands are buffer-local and only available in markdown buffers.

You can also call the Lua API functions directly if needed:

>vim
    :lua require('markdown-plus').headers.generate_toc()
    :lua require('markdown-plus').headers.open_toc_window()
    :lua require('markdown-plus').list.renumber_ordered_lists()
    :lua require('markdown-plus').format.toggle_format('bold')
    :lua require('markdown-plus').links.insert_link()
    :lua require('markdown-plus').quote.toggle_quote()
<

See |markdown-plus-api| for a complete list of available functions.


==============================================================================
6. API                                                         *markdown-plus-api*

For plugin developers or advanced users, markdown-plus.nvim exposes a Lua API:


HEADERS MODULE                                        *markdown-plus.headers*

                                                    *markdown-plus.headers.promote*
markdown-plus.headers.promote_header()
    Promotes the header on the current line (adds a `#`).

                                                     *markdown-plus.headers.demote*
markdown-plus.headers.demote_header()
    Demotes the header on the current line (removes a `#`).

                                                *markdown-plus.headers.generate_toc*
markdown-plus.headers.generate_toc()
    Generates a Table of Contents at cursor position.
    Returns: nothing. Shows error message if TOC already exists.

                                                  *markdown-plus.headers.update_toc*
markdown-plus.headers.update_toc()
    Updates the existing Table of Contents.

                                                *markdown-plus.headers.follow_link*
markdown-plus.headers.follow_link()
    Follows the TOC link under cursor.
    Returns: boolean - true if a link was followed, false otherwise.

                                            *markdown-plus.headers.open_toc_window*
markdown-plus.headers.open_toc_window({window_type})
    Opens an interactive Table of Contents window.
    
    Parameters: ~
        {window_type}  (string, optional) Window layout:
                      - 'vertical' (default): vertical split
                      - 'horizontal': horizontal split
                      - 'tab': new tab
    
    Features: ~
        - Toggle on/off (no duplicate windows)
        - Progressive disclosure (shows H1-H2 initially)
        - Expand/collapse with l/h keys
        - Jump to headers with <Enter>
        - Help popup with ?
        - Syntax highlighting
        - Auto-sizing
    
    Keymaps (inside TOC): ~
        l         - Expand header to show children
        h         - Collapse header or jump to parent
        <Enter>   - Jump to header in source buffer
        q         - Close TOC window
        ?         - Show help popup
    
    Example: ~
>lua
        require('markdown-plus').headers.open_toc_window()  -- vertical
        require('markdown-plus').headers.open_toc_window('horizontal')
<

                                               *markdown-plus.headers.next_header*
markdown-plus.headers.next_header()
    Jumps to the next header in the document.

                                               *markdown-plus.headers.prev_header*
markdown-plus.headers.prev_header()
    Jumps to the previous header in the document.

                                          *markdown-plus.headers.set_header_level*
markdown-plus.headers.set_header_level(level)
    Sets the current line to a specific header level (1-6).
    Parameters: ~
        {level}  (number) The header level (1 = #, 2 = ##, etc.)


LIST MODULE                                              *markdown-plus.list*

                                              *markdown-plus.list.handle_enter*
markdown-plus.list.handle_enter()
    Handles Enter key in insert mode for auto-continuing lists or splitting
    list content at cursor position. When cursor is in the middle of list
    content, creates a new list item with the remaining content.

                                        *markdown-plus.list.continue_list_content*
markdown-plus.list.continue_list_content()
    Continue list content on next line. Creates a continuation line with
    proper indentation aligned with the list content start position. Typically
    bound to Alt+Enter (<A-CR>) in insert mode.

                                                *markdown-plus.list.handle_tab*
markdown-plus.list.handle_tab()
    Handles Tab key in insert mode for indenting list items.

                                          *markdown-plus.list.handle_shift_tab*
markdown-plus.list.handle_shift_tab()
    Handles Shift-Tab key in insert mode for dedenting list items.

                                          *markdown-plus.list.handle_backspace*
markdown-plus.list.handle_backspace()
    Handles Backspace key in insert mode with smart list removal.

                                         *markdown-plus.list.handle_normal_o*
markdown-plus.list.handle_normal_o()
    Handles 'o' key in normal mode for creating new list items below.

                                         *markdown-plus.list.handle_normal_O*
markdown-plus.list.handle_normal_O()
    Handles 'O' key in normal mode for creating new list items above.

                                    *markdown-plus.list.renumber_ordered_lists*
markdown-plus.list.renumber_ordered_lists()
    Manually triggers renumbering of all ordered lists in the buffer.

                                          *markdown-plus.list.debug_list_groups*
markdown-plus.list.debug_list_groups()
    Debug function that prints detected list groups to help troubleshoot
    list recognition issues. Used for development and debugging.


FORMAT MODULE                                          *markdown-plus.format*

                                             *markdown-plus.format.toggle_format*
markdown-plus.format.toggle_format(format_type)
    Toggles formatting on visual selection or current word.
    Parameters: ~
        {format_type}  (string) One of: 'bold', 'italic', 'strikethrough', 'code'

                                        *markdown-plus.format.toggle_format_word*
markdown-plus.format.toggle_format_word(format_type)
    Toggles formatting on the word under cursor.
    Parameters: ~
        {format_type}  (string) One of: 'bold', 'italic', 'strikethrough', 'code'

                                        *markdown-plus.format.convert_to_code_block*
markdown-plus.format.convert_to_code_block()
    Converts the selected text to a code block. Prompts for the language of the
    code block.


                                        *markdown-plus.format.clear_formatting*
markdown-plus.format.clear_formatting()
    Clears all formatting from visual selection.

                                   *markdown-plus.format.clear_formatting_word*
markdown-plus.format.clear_formatting_word()
    Clears all formatting from the word under cursor.


LINKS MODULE                                            *markdown-plus.links*

                                               *markdown-plus.links.insert_link*
markdown-plus.links.insert_link()
    Inserts a new markdown link at cursor position. Prompts for link text
    and URL.

                                         *markdown-plus.links.selection_to_link*
markdown-plus.links.selection_to_link()
    Converts visual selection to a markdown link. Prompts for URL.

                                                 *markdown-plus.links.edit_link*
markdown-plus.links.edit_link()
    Edits the link under cursor. Works with both inline and reference-style
    links. Prompts for new text and URL/reference.

                                            *markdown-plus.links.auto_link_url*
markdown-plus.links.auto_link_url()
    Converts a bare URL under cursor to a markdown link. Prompts for link
    text (defaults to URL if left empty).

                                        *markdown-plus.links.convert_to_reference*
markdown-plus.links.convert_to_reference()
    Converts an inline link `[text](url)` to reference-style `[text][ref]`.
    Adds reference definition at end of document. Reuses existing references
    when possible.

                                           *markdown-plus.links.convert_to_inline*
markdown-plus.links.convert_to_inline()
    Converts a reference-style link `[text][ref]` to inline `[text](url)`.
    Looks up the reference definition in the document.

                                        *markdown-plus.links.find_reference_url*
markdown-plus.links.find_reference_url(ref)
    Finds and returns the URL for a given reference ID.
    Parameters: ~
        {ref}  (string) The reference ID to look up
    Returns: ~
        (string|nil) The URL if found, nil otherwise

QUOTES MODULE                                           *markdown-plus.quote*

                                               *markdown-plus.quote.toggle_quote*
markdown-plus.quote.toggle_quote()
    Toggles blockquote on the current line or visual selection.

Example usage:
>lua
    -- Call API functions directly
    require('markdown-plus').headers.generate_toc()
    require('markdown-plus').list.renumber_ordered_lists()
    require('markdown-plus').format.toggle_format('bold')
    require('markdown-plus').headers.set_header_level(2)
    require('markdown-plus').links.insert_link()
    require('markdown-plus').links.convert_to_reference()
    require('markdown-plus').quote.toggle_quote()
<


==============================================================================
7. Troubleshooting                                 *markdown-plus-troubleshooting*


ISSUE: KEYMAPS NOT WORKING ~

Ensure the plugin is loaded for Markdown files. Check with:
>vim
    :verbose map <your-keymap>
<

If nothing shows up, the filetype might not be set correctly:
>vim
    :set filetype?
<

Should show `filetype=markdown`.


ISSUE: O AND <CR> NOT ENTERING INSERT MODE ~

This was a known issue in older versions. Update to the latest version where
`o` and `O` properly enter insert mode when used on non-list lines.


ISSUE: TOC GENERATION CREATES DUPLICATES ~

The plugin now prevents duplicate TOCs by using HTML comment markers
(`<!-- TOC -->` and `<!-- /TOC -->`). If you have an old-style TOC without
markers, you may need to manually add them or delete the old TOC and generate
a new one.


ISSUE: LIST OPERATIONS AFFECTING NON-LIST TEXT ~

The plugin is designed to be context-aware. If list operations are affecting
non-list text, please report this as a bug with a minimal example.


ISSUE: FORMATTING TOGGLE NOT WORKING ~

Ensure you're using the correct keymap. By default:
- `<leader>mb` for bold
- `<leader>mi` for italic
- `<leader>ms` for strikethrough
- `<leader>mc` for inline code
- `<leader>mC` for clearing formatting
- `<leader>mq` for toggling blockquote

These work in both normal mode (on word under cursor) and visual mode
(on selection).

Check your leader key with:
>vim
    :echo mapleader
<


==============================================================================
8. Contributing                                       *markdown-plus-contributing*

Contributions are welcome! The plugin follows these principles:

1. Context-aware behavior: Operations should only affect relevant text
2. Vim conventions: Respect normal Vim behavior and mappings
3. Performance: Keep operations fast and lightweight
4. Minimal configuration: Sensible defaults with easy customization

See CONTRIBUTING.md in the repository for detailed guidelines on:
- Code style and structure
- Testing requirements
- Pull request process
- Feature requests


==============================================================================
9. License                                                 *markdown-plus-license*

markdown-plus.nvim is licensed under the MIT License.
See LICENSE file in the repository for full details.

Copyright (c) 2025 Yousef Hadder

==============================================================================
vim:tw=78:ts=8:ft=help:norl: