Skip to content

4.Usage

Jump to bottom
yousefhadder edited this page Dec 10, 2025 · 2 revisions

Usage Examples

The plugin automatically activates when you open a markdown file (.md extension). All features work seamlessly with Neovim's built-in functionality.

List Management Examples

Auto-continue Lists

- Type your first item and press Enter
- The next item is automatically created ⬅️ (cursor here)

Split List Content

- This is some content in| the middle
  Press Enter splits at cursor:
- This is some content in
- the middle ⬅️ (cursor here, new item created with remaining content)

Continue Content Without New Bullet

- This is a longer list item that|
  Press Alt+Enter to continue on next line:
- This is a longer list item that
  continues here ⬅️ (same item, no new bullet)

Checkbox Lists

- [ ] Press Enter after this unchecked item
- [ ] Next checkbox item is created ⬅️ (cursor here)

1. [x]
2. [ ]

Toggle Checkboxes

Position cursor on a list item and press <leader>mx:

- Regular item       ← Press <leader>mx
- [ ] Regular item   ← Press <leader>mx again
- [x] Regular item   ← Press <leader>mx again (cycles back to unchecked)

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

Visual mode - select multiple lines and press <leader>mx:
- [ ] Task 1         → - [x] Task 1
- [x] Task 2         → - [ ] Task 2
- Regular            → - [ ] Regular

Insert mode - press Ctrl+T while on a list item:
- [ ] Todo           → - [x] Todo (cursor stays in place)

Smart Indentation

- Top level item
  - Press Tab to indent ⬅️ (cursor here)
    - Press Tab again for deeper nesting
  - Press Shift+Tab to outdent ⬅️ (cursor here)

List Breaking

- Type your item
-
  ⬆️ Press Enter on empty item, then Enter again to break out:

Regular paragraph text continues here.

Smart Backspace

- Type some text, then delete it all
- ⬅️ Press Backspace here to remove the bullet entirely

Normal Mode List Creation

- Position cursor on this list item
- Press 'o' to create next item ⬅️ (new item appears below)
- Press 'O' to create previous item ⬅️ (new item appears above)

1. Works with ordered lists too
2. Press 'o' to create item 3 below ⬅️
3. Press 'O' to create item between 2 and 3 ⬅️

a. Letter-based lists supported
b. Press 'o' for next letter ⬅️
c. Press 'O' for previous letter ⬅️

1) Parenthesized lists work too
2) Auto-increments correctly ⬅️

Text Formatting Examples

Toggle Bold

Position cursor on word and press <leader>mb:
text → **text**
**text** → text (toggle off)

Or select text in visual mode and press <leader>mb:
Select "this text" → **this text**

Toggle Italic

Position cursor on word and press <leader>mi:
text → *text*
*text* → text (toggle off)

Toggle Strikethrough

Position cursor on word and press <leader>ms:
text → ~~text~~
~~text~~ → text (toggle off)

Toggle Inline Code

Position cursor on word and press <leader>mc:
text → `text`
`text` → text (toggle off)

Toggle Highlight

Position cursor on word and press <leader>mh:
text → ==text==
==text== → text (toggle off)

Toggle Underline

Position cursor on word and press <leader>mu:
text → ++text++
++text++ → text (toggle off)

Convert to Code Block

Select any text in visual block mode and convert it to a code block:
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 (e.g., `lua`, `python`)

Example:
This is some text
and more text

→

    ```txt
    This is some text
    and more text
    ```

Clear All Formatting

Position cursor on formatted word and press <leader>mC:
**bold** *italic* `code` → bold italic code

Or select complex formatted text and press <leader>mC:
This **bold** and *italic* text → This bold and italic text

Smart Word Detection

Works with special characters in words:
test-with-hyphens → **test-with-hyphens** (entire word formatted)
file.name.here → *file.name.here* (entire word formatted)
snake_case_word → `snake_case_word` (entire word formatted)

Visual Mode Selection

Select any text in visual mode and format it:
1. Enter visual mode with 'v'
2. Select the text you want to format
3. Press <leader>mb (or mi, ms, mc, mC)
4. The entire selection will be formatted

Example: Select "multiple words here" → **multiple words here**

Headers & TOC Examples

Header Navigation

Use ]] and [[ to jump between headers quickly:
# Main Title       ← Press ]] to jump here
Content
## Section 1       ← Press ]] to jump here
Content
### Subsection    ← Press ]] to jump here
Content
Press [[ to jump backwards

Promote/Demote Headers

Position cursor on any header and adjust its level:
### Subsection    ← Press <leader>h+ → ## Subsection (promoted)
## Section        ← Press <leader>h- → ### Section (demoted)

Convert to Header

Position cursor on any line:
Regular text      ← Press <leader>h2 → ## Regular text
Already header    ← Press <leader>h4 → #### Already header

Generate Table of Contents

# My Document

Press <leader>ht to generate TOC:

<!-- TOC -->

## Table of Contents

- [Section 1](#section-1)
  - [Subsection 1.1](#subsection-1-1)
- [Section 2](#section-2)

<!-- /TOC -->

## Section 1
...

Note: The TOC is wrapped in HTML comment markers <!-- TOC --> and <!-- /TOC -->. This prevents duplicate TOCs from being created if you press <leader>ht again. To update an existing TOC, use <leader>hu instead.

Update TOC

After adding/removing/renaming headers:
1. Press <leader>hu to update the TOC
2. All links are regenerated automatically
3. The content between <!-- TOC --> and <!-- /TOC --> is replaced

Follow TOC Links

## Table of Contents

- [Getting Started](#getting-started)  ← Position cursor here
- [API & SDK](#api--sdk)
- [Q&A](#qa)

Press gd to jump directly to that header!

## Getting Started    ← You jump here instantly!

TOC with Symbols (GitHub-Compatible)

# API Documentation

## Q&A              → TOC link: [Q&A](#qa)
## API & SDK        → TOC link: [API & SDK](#api--sdk)
## C++ Examples     → TOC link: [C++ Examples](#c-examples)
## What's New?      → TOC link: [What's New?](#whats-new)

All links work correctly on GitHub! ✓

Code Blocks Ignored

# Document

## Real Section

\`\`\`bash
# This is NOT in the TOC
## Neither is this
\`\`\`

Press <leader>ht → Only "Real Section" appears in TOC ✓

TOC Window (Navigable)

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

: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 navigation: l to expand, h to collapse
  • 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

Example:

Initial View (depth 1-2):
[H1] Main Title
▶ [H2] Getting Started
▶ [H2] Features
▶ [H2] Contributing

After pressing 'l' on "Getting Started":
[H1] Main Title
▼ [H2] Getting Started
    ▶ [H3] Installation
    ▶ [H3] Configuration
▶ [H2] Features
▶ [H2] Contributing

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

Links & References Examples

Insert New Link

In normal mode, press <leader>ml:
1. You'll be prompted: "Link text: "
2. Enter the text (e.g., "GitHub")
3. You'll be prompted: "URL: "
4. Enter the URL (e.g., "https://github.com")
5. Result: [GitHub](https://github.com)

Convert Selection to Link

Select text in visual mode:
Visit my website  ← Select "my website" with visual mode

Press <leader>ml:
1. You'll be prompted: "URL: "
2. Enter URL (e.g., "https://example.com")
3. Result: Visit [my website](https://example.com)

Edit Existing Link

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

[Old Text](https://old-url.com)  ← cursor here

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)

Open Link in Browser

Use native Neovim functionality:
[Google](https://google.com)  ← Position cursor here
Press gx to open in browser

https://example.com  ← Works on bare URLs too
Press gx to open

Convert URL to Link

Position cursor on a URL and press <leader>ma:

Check out https://github.com/yousefhadder/markdown-plus.nvim

Press <leader>ma:
1. Link text (empty for URL): GitHub Plugin
2. Result: Check out [GitHub Plugin](https://github.com/yousefhadder/markdown-plus.nvim)

Or leave text empty to use URL as text:
Result: [https://github.com/yousefhadder/markdown-plus.nvim](https://github.com/yousefhadder/markdown-plus.nvim)

Reference-Style Links

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

[Documentation](https://docs.example.com)  ← cursor here

Press <leader>mR:
Result:
[Documentation][documentation]

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

---

Convert reference link to inline with <leader>mI:

[My Link][myref]  ← cursor here

... (elsewhere in document)
[myref]: https://myref.com

Press <leader>mI:
Result: [My Link](https://myref.com)

Reuse Existing References

When converting links with the same text and URL to reference-style,
the reference is reused:

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:

[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

Image Links Examples

Insert New Image Link

In normal mode, press <leader>mL:
1. You'll be prompted: "Alt text: "
2. Enter alt text (e.g., "Screenshot")
3. You'll be prompted: "URL: "
4. Enter URL (e.g., "images/screenshot.png")
5. You'll be prompted: "Title (optional): "
6. Enter title or leave empty

Result: ![Screenshot](images/screenshot.png)
Or with title: ![Screenshot](images/screenshot.png "My Screenshot")

Convert Selection to Image

Select text in visual mode:
A beautiful sunset  ← Select "A beautiful sunset" with visual mode

Press <leader>mL:
1. You'll be prompted: "URL: "
2. Enter URL (e.g., "photos/sunset.jpg")
3. You'll be prompted: "Title (optional): "
4. Enter title or leave empty

Result: ![A beautiful sunset](photos/sunset.jpg)

Edit Existing Image

Position cursor anywhere on an image and press <leader>mE:

![Old Alt](old-image.png)  ← cursor here

Press <leader>mE:
1. Alt text: Old Alt (edit or press Enter)
2. URL: old-image.png (edit or press Enter)
3. Title (optional): (edit, add, or press Enter)

Result: ![New Alt](new-image.png "Updated Title")

Toggle Between Link and Image

# Convert regular link to image:
[My Photo](photo.jpg)  ← cursor here

Press <leader>mA:
Result: ![My Photo](photo.jpg)

# Convert image back to regular link:
![My Photo](photo.jpg)  ← cursor here

Press <leader>mA:
Result: [My Photo](photo.jpg)

Working with Titles

Images can have optional title attributes that appear as tooltips:

![Diagram](diagrams/flow.svg "System Architecture Diagram")

When editing, you can:
- Add a title to an image that doesn't have one
- Modify an existing title
- Remove a title by leaving it empty

Press <leader>mE on the image:
1. Alt text: Diagram
2. URL: diagrams/flow.svg
3. Title (optional): System Architecture Diagram
   (Leave empty to remove)

Common Use Cases

# Local images:
![Logo](./assets/logo.png)
![Icon](../images/icon.svg)

# Remote images:
![Banner](https://example.com/banner.jpg)

# With title attributes:
![Graph](data/graph.png "Q4 Sales Performance")
![Screenshot](screens/demo.png "Feature Demo")

# Converting selections quickly:
Select: Product Image
Press <leader>mL
Enter URL: products/item-42.jpg
Result: ![Product Image](products/item-42.jpg)

Quotes Management Examples

Toggle Blockquote

Position cursor on a line and press `<leader>mq`:
This is a normal line → `> This is a normal line`
`> This is a quoted line` → This is a normal line (toggle off)

Visual Mode Selection

Select multiple lines in visual mode and press `<leader>mq`:
1. Enter visual mode with `V` (line-wise visual mode)
2. Select the lines you want to quote
3. Press `<leader>mq`

Example:
Normal line 1
Normal line 2

→

> Normal line 1
> Normal line 2

Callouts/Admonitions Examples (GitHub Flavored Markdown)

Insert Callout

Position cursor on an empty line or existing line and press `<leader>mQi`:
1. A menu appears with callout types: NOTE, TIP, IMPORTANT, WARNING, CAUTION
2. Select your desired type
3. Callout is inserted and you enter insert mode

Empty line example:
█

→ (after selecting "NOTE")

> [!NOTE]
> █

Existing content example:
Some existing content

→ (after selecting "WARNING")

> [!WARNING]
> █
Some existing content

Wrap Selection in Callout

Select text in visual mode and press `<leader>mQi`:
1. Enter visual mode with `V` (line-wise)
2. Select the lines to wrap
3. Press `<leader>mQi`
4. Choose callout type

Example:
This is important information
Users should pay attention to this

→ (after selecting "IMPORTANT")

> [!IMPORTANT] This is important information
> Users should pay attention to this

Toggle Callout Type

Position cursor in a callout and press `<leader>mQt` to cycle through types:

> [!NOTE]
> Some content

→ Press `<leader>mQt`

> [!TIP]
> Some content

→ Press `<leader>mQt` again

> [!IMPORTANT]
> Some content

Continues cycling: NOTE → TIP → IMPORTANT → WARNING → CAUTION → NOTE

Convert Blockquote to Callout

Position cursor in a blockquote and press `<leader>mQc`:

> This is a regular blockquote
> With multiple lines

→ (after selecting "WARNING")

> [!WARNING] This is a regular blockquote
> With multiple lines

Convert Callout to Blockquote

Position cursor in a callout and press `<leader>mQb`:

> [!CAUTION]
> This was a callout

→

>
> This was a callout

All Callout Types

GitHub renders these with distinct colors and icons:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Custom Callout Types

require("markdown-plus").setup({
  callouts = {
    default_type = "TIP",  -- Change default from NOTE to TIP
    custom_types = { "DANGER", "SUCCESS" },  -- Add custom types
  },
})

After configuration, your custom types will appear in the selection menu and can be cycled through with <leader>mQt.

Table Support Examples

Create a New Table

Press <leader>tc to create a new table interactively:
1. You'll be prompted: "Number of rows: "
2. Enter the number of rows (e.g., 3)
3. You'll be prompted: "Number of columns: "
4. Enter the number of columns (e.g., 4)

Result:
| Header 1 | Header 2 | Header 3 | Header 4 |
|----------|----------|----------|----------|
|          |          |          |          |
|          |          |          |          |
|          |          |          |          |

Format and Normalize Tables

Format a table with <leader>tf:
| Name | Age | City |
|---|---|---|
| Alice | 25 | NYC |
| Bob | 30 | LA |

→

| Name  | Age | City |
|-------|-----|------|
| Alice | 25  | NYC  |
| Bob   | 30  | LA   |

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

→

| Header 1         | Header 2          |
|------------------|-------------------|
| Missing pipes    | fixed automatically |

Row Operations

Insert row below with <leader>tir:
| Name | Age |
|------|-----|
| Alice | 25 | ← cursor here
| Bob  | 30 |

→

| Name  | Age |
|-------|-----|
| Alice | 25  |
|       |     | ← new row inserted
| Bob   | 30  |

Insert row above with <leader>tiR:
| Name  | Age |
|-------|-----|
|       |     | ← new row inserted
| Alice | 25  | ← cursor was here

Delete row with <leader>tdr:
| Name  | Age |
|-------|-----|
| Alice | 25  | ← cursor here (row deleted)
| Bob   | 30  |

→

| Name | Age |
|------|-----|
| Bob  | 30  |

Duplicate row with <leader>tyr:
| Name  | Age |
|-------|-----|
| Alice | 25  | ← cursor here
| Bob   | 30  |

→

| Name  | Age |
|-------|-----|
| Alice | 25  |
| Alice | 25  | ← duplicated row
| Bob   | 30  |

Column Operations

Insert column right with <leader>tic:
| Name  | Age |
|-------|-----|
| Alice | 25  |
| Bob   | 30  |
       ↑ cursor here

→

| Name  | Age |     |
|-------|-----|-----|
| Alice | 25  |     | ← new column
| Bob   | 30  |     |

Insert column left with <leader>tiC:
|     | Name  | Age | ← new column inserted left
|-----|-------|-----|
|     | Alice | 25  |
|     | Bob   | 30  |

Delete column with <leader>tdc:
| Name  | Age | City | ← Age column deleted
|-------|-----|------|
| Alice | 25  | NYC  |

→

| Name  | City |
|-------|------|
| Alice | NYC  |

Duplicate column with <leader>tyc:
| Name  | Age | Age | ← Age column duplicated
|-------|-----|-----|
| Alice | 25  | 25  |
| Bob   | 30  | 30  |

Alignment Support

Tables support left, center, and right alignment:

Left-aligned (default):     :---
Center-aligned:             :---:
Right-aligned:              ---:

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

Formatting preserves alignment markers.

Insert Mode Navigation

Navigate table cells in insert mode with Alt+hjkl:

| Name  | Age | City     |
|-------|-----|----------|
| Alice | 25  | New York | ← cursor here
| Bob   | 30  | LA       |

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

Press <A-j> (Alt+j) to move down:
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 25  | New York |
| Bob   | 30  | LA       | ← cursor moves down
          ^

Wrapping behavior (circular navigation):
- <A-l> at last column wraps to first column
- <A-h> at first column wraps to last column
- <A-j> at last row wraps to header row
- <A-k> at header row wraps to last data row

Falls back to arrow keys when not in a table.

Cell Operations

Toggle cell alignment with <leader>ta:
| Left | Center | Right |
|------|--------|-------|
| A    | B      | C     |
      ↑ cursor here, press <leader>ta

→ Cycles through:
| Left | Center | Right |
|:-----|--------|-------| (left-aligned)
|:-----|:------:|-------| (center-aligned)
|:-----|:------:|------:| (right-aligned)
|------|--------|-------| (back to left)

Clear cell content with <leader>tx:
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 25  | New York |
              ↑ cursor here, press <leader>tx

→
| Name  | Age | City     |
|-------|-----|----------|
| Alice |     | New York | (content cleared, structure intact)

Row and Column Movement

Move row up with <leader>tmk:
| Name  | Age |
|-------|-----|
| Alice | 25  |
| Bob   | 30  | ← cursor here
| Carol | 35  |

→
| Name  | Age |
|-------|-----|
| Bob   | 30  | (moved up)
| Alice | 25  |
| Carol | 35  |

Move row down with <leader>tmj:
| Name  | Age |
|-------|-----|
| Alice | 25  | ← cursor here
| Bob   | 30  |
| Carol | 35  |

→
| Name  | Age |
|-------|-----|
| Bob   | 30  |
| Alice | 25  | (moved down)
| Carol | 35  |

Move column left with <leader>tmh:
| Name  | Age | City |
|-------|-----|------|
| Alice | 25  | NYC  |
              ↑ cursor here

→
| Age | Name  | City |
|-----|-------|------|
| 25  | Alice | NYC  | (Age column moved left)

Move column right with <leader>tml:
| Name  | Age | City |
|-------|-----|------|
| Alice | 25  | NYC  |
        ↑ cursor here

→
| Age | Name  | City |
|-----|-------|------|
| 25  | Alice | NYC  | (Name column moved right)

Advanced Operations

Transpose table with <leader>tt:
| Name  | Age | City        |
|-------|-----|-------------|
| Alice | 30  | New York    |
| Bob   | 25  | Los Angeles |
↑ cursor anywhere in table, press <leader>tt, confirm

→
| Name | Alice    | Bob         |
|------|----------|-------------|
| Age  | 30       | 25          |
| City | New York | Los Angeles |
(Rows become columns, columns become rows)

Sort by column ascending with <leader>tsa:
| Name  | Age | City        |
|-------|-----|-------------|
| Bob   | 30  | Los Angeles |
| Alice | 25  | New York    |
| Carol | 35  | Chicago     |
        ↑ cursor in Age column, press <leader>tsa, confirm

→
| Name  | Age | City        |
|-------|-----|-------------|
| Alice | 25  | New York    | (sorted by age ascending)
| Bob   | 30  | Los Angeles |
| Carol | 35  | Chicago     |

Sort by column descending with <leader>tsd:
| Product | Price |
|---------|-------|
| Apple   | 1.50  |
| Banana  | 0.75  |
| Orange  | 2.00  |
           ↑ cursor in Price column, press <leader>tsd, confirm

→
| Product | Price |
|---------|-------|
| Orange  | 2.00  | (sorted by price descending)
| Apple   | 1.50  |
| Banana  | 0.75  |

Convert table to CSV with <leader>tvx:
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 25  | New York |
| Bob   | 30  | LA       |
↑ cursor anywhere in table, press <leader>tvx

→
Name,Age,City
Alice,25,New York
Bob,30,LA
(Table replaced with CSV format)

Convert CSV to table with <leader>tvi:
Name,Age,City
Alice,25,New York
Bob,30,LA
↑ cursor on any CSV line, press <leader>tvi

→
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 25  | New York |
| Bob   | 30  | LA       |
(CSV converted to formatted table)

Handles quoted CSV fields with commas:
"Last, First",Age,"City, State"
"Smith, John",30,"New York, NY"

→
| Last, First | Age | City, State  |
|-------------|-----|---------------|
| Smith, John | 30  | New York, NY |

Edge Cases

Tables handle various edge cases:

Empty cells:
| Header 1 | Header 2 |
|----------|----------|
|          | Data     |
| Data     |          |

Special characters:
| Name      | Symbol |
|-----------|--------|
| Greater   | >      |
| Less      | <      |
| Pipe      | \|     |

Unicode:
| English | Japanese | Emoji |
|---------|----------|-------|
| Hello   | こんにちは | 👋    |
| World   | 世界     | 🌍    |

Malformed tables (normalized automatically):
| No closing pipe
| Missing separator
    →
| No closing pipe    |
|--------------------|
| Missing separator  |

Smart Features

**Header Protection:**
Cannot delete header row or separator row. Operations protect table integrity.

**Minimum Constraints:**
- Cannot delete the last column
- Cannot delete the only data row
- Maintains at least one header + separator + one data row

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

Clone this wiki locally