1. 🚀 Introduction
2. ✨ Features
   1. 🧭 Navigation
   2. 🔗 Link and reference handling
   3. 📊 Table support
   4. 📝 List support
   5. ✅ To-do list support
   6. 📁 File management
   7. 🪗 Folding
   8. 🔮 Completion
   9. 🧩 YAML block parsing
   10. 🖌️ Visual enhancements
3. 💾 Installation
4. ⚙️ Configuration
   1. ⚡ Quick start
   2. 🔧 Advanced configuration and sample recipes
5. 🛠️ Commands & mappings
   1. Custom mappings
6. 📚 API
   1. Initialization
   2. Link management
   3. Link and path handling
   4. Templates
   5. Buffer navigation
   6. Cursor movement
   7. Cursor-aware manipulations
   8. List management
   9. To-do list management
   10. Table management
   11. Folds
   12. Yaml blocks
   13. Bibliography
   14. Statusline components
7. 🤝 Contributing
8. 🔢 Version information
9. 🔗 Related projects
   1. Competition
   2. Complementary plugins

Mkdnflow is designed for the fluent navigation and management of markdown documents and document collections (notebooks, wikis, etc). It features numerous convenience functions that make it easier to work within raw markdown documents or document collections: link and reference handling (🔗 Link and reference handling), navigation (🧭 Navigation), table support (📊 Table support), list (📝 List support) and to-do list (✅ To-do list support) support, file management (📁 File management), section folding (🪗 Folding), and more. Use it for notetaking, personal knowledge management, static website building, and more. Most features are highly tweakable (⚙️ Configuration).

• Jump to links
• Jump to section headings

• Link following
  • Open markdown and other text filetypes in the current window
  • Open other filetypes and URLs with your system's default application
• Browser-like 'Back' and 'Forward' functionality
• Table of contents window

• Link creation from a visual selection or the text under the cursor
• Link destruction
• Follow links to local paths and other Markdown files
• Follow external links (open using default application)
• Follow .bib-based references
  • Open url or doi field in the default browser
  • Open documents specified in file field
• Implicit filetype extensions
• Support for various link types
  • Standard Markdown links ([my page](my_page.md))
  • Wiki links (direct [[my page]] or piped [[my_page.md|my page]])
  • Automatic links (<https://my.page>)
  • Reference-style links ([my page][1] with [1]: my_page.md)
  • Image links (![alt text](image.png)) — opened in system viewer
  • Citations (@citekey or Pandoc-style [@citekey])
  • Footnotes ([^1] with [^1]: Footnote text)

• Table creation
• Table extension (add rows and columns)
• Table formatting
• Pandoc grid table support
• Column alignment (left, right, center)
• Paste delimited data as a table
• Import delimited file into a new table

• Automatic list extension
• Sensible auto-indentation and auto-dedentation
• Ordered list number updating

• Toggle to-do item status
• Status propagation
• To-do list sorting
• Create to-do items from plain ordered or unordered list items
• Customizable highlighting for to-do status markers and content

• Simultaneous link and file renaming
• As-needed directory creation

• Section folding and fold toggling
• Helpful indicators for folded section contents
  • Section heading level
  • Counts of Markdown objects (tables, lists, code blocks, etc.)
  • Line and word counts
• YAML block folding

• Path completion
• Completion of bibliography items

• Specify a bibliography file in YAML front matter

• Conceal markdown and wiki link syntax
• Extended link highlighting
  • Automatic links
  • Wiki links

Requirements:

• Linux, macOS, or Windows
• Neovim >= 0.9.5 (tested on 0.9.5, 0.10.x, and stable)

Install Mkdnflow using your preferred package manager for Neovim. Once installed, Mkdnflow is configured and initialized using a setup function.

require('lazy').setup({
    -- Your other plugins
    {
        'jakewvincent/mkdnflow.nvim',
        ft = { 'markdown', 'rmd' },  -- Add custom filetypes here if configured
        config = function()
            require('mkdnflow').setup({
                -- Your config
            })
        end
    }
    -- Your other plugins
})

" Vim-Plug
Plug 'jakewvincent/mkdnflow.nvim'

" Include the setup function somewhere else in your init.vim file, or the
" plugin won't activate itself:
lua << EOF
require('mkdnflow').setup({
    -- Config goes here; leave blank for defaults
})
EOF

Mkdnflow is configured and initialized using a setup function. To use the default settings, pass no arguments or an empty table to the setup function:

{
    'jakewvincent/mkdnflow.nvim',
    config = function()
        require('mkdnflow').setup({})
    end
}

Most features are highly configurable. Study the default config first and read the documentation for the configuration options below or in the help files.

{
    modules = {
        bib = true,
        buffers = true,
        conceal = true,
        cursor = true,
        folds = true,
        foldtext = true,
        links = true,
        lists = true,
        maps = true,
        paths = true,
        tables = true,
        templates = true,
        to_do = true,
        yaml = false,
        cmp = false,
    },
    create_dirs = true,
    silent = false,
    wrap = false,
    on_attach = false,
    path_resolution = {
        primary = 'first',
        fallback = 'current',
        root_marker = false,
        sync_cwd = false,
        update_on_navigate = true,
    },
    filetypes = {
        markdown = true,
        rmd = true,
    },
    foldtext = {
        object_count = true,
        object_count_icon_set = 'emoji',
        object_count_opts = function()
            return require('mkdnflow').foldtext.default_count_opts()
        end,
        line_count = true,
        line_percentage = true,
        word_count = false,
        title_transformer = function()
            return require('mkdnflow').foldtext.default_title_transformer
        end,
        fill_chars = {
            left_edge = '⢾⣿⣿',
            right_edge = '⣿⣿⡷',
            item_separator = ' · ',
            section_separator = ' ⣹⣿⣏ ',
            left_inside = ' ⣹',
            right_inside = '⣏ ',
            middle = '⣿',
        },
    },
    bib = {
        default_path = nil,
        find_in_root = true,
    },
    cursor = {
        jump_patterns = nil,
    },
    links = {
        style = 'markdown',
        compact = false,
        conceal = false,
        search_range = 0,
        implicit_extension = nil,
        transform_on_follow = false,
        transform_on_create = function(text)
            text = text:gsub('[ /]', '-')
            text = text:lower()
            text = os.date('%Y-%m-%d_') .. text
            return text
        end,
        transform_scope = 'path',
        auto_create = true,
        on_create_new = false,
    },
    new_file_template = {
        enabled = false,
        placeholders = {
            before = {
                title = 'link_title',
                date = 'os_date',
            },
            after = {},
        },
        template = '# {{ title }}',
    },
    to_do = {
        highlight = false,
        statuses = {
            {
                name = 'not_started',
                symbol = ' ',
                colors = {
                    marker = { link = 'Conceal' },
                    content = { link = 'Conceal' },
                },
                sort = { section = 2, position = 'top' },
                skip_on_toggle = false,
                propagate = {
                    up = function(host_list) ... end,
                    down = function(child_list) ... end,
                },
            },
            {
                name = 'in_progress',
                symbol = '-',
                colors = {
                    marker = { link = 'WarningMsg' },
                    content = { bold = true },
                },
                sort = { section = 1, position = 'bottom' },
                skip_on_toggle = false,
                propagate = {
                    up = function(host_list) ... end,
                    down = function(child_list) end,
                },
            },
            {
                name = 'complete',
                symbol = { 'X', 'x' },
                colors = {
                    marker = { link = 'String' },
                    content = { link = 'Conceal' },
                },
                sort = { section = 3, position = 'top' },
                skip_on_toggle = false,
                propagate = {
                    up = function(host_list) ... end,
                    down = function(child_list) ... end,
                },
            },
        },
        status_propagation = {
            up = true,
            down = true,
        },
        sort = {
            on_status_change = false,
            recursive = false,
            cursor_behavior = {
                track = true,
            },
        },
    },
    tables = {
        type = 'pipe',
        trim_whitespace = true,
        format_on_move = true,
        auto_extend_rows = false,
        auto_extend_cols = false,
        style = {
            cell_padding = 1,
            separator_padding = 1,
            outer_pipes = true,
            apply_alignment = true,
        },
    },
    yaml = {
        bib = { override = false },
    },
    mappings = {
        MkdnEnter = { { 'n', 'v' }, '<CR>' },
        MkdnGoBack = { 'n', '<BS>' },
        MkdnGoForward = { 'n', '<Del>' },
        MkdnMoveSource = { 'n', '<F2>' },
        MkdnNextLink = { 'n', '<Tab>' },
        MkdnPrevLink = { 'n', '<S-Tab>' },
        MkdnFollowLink = false,
        MkdnDestroyLink = { 'n', '<M-CR>' },
        MkdnTagSpan = { 'v', '<M-CR>' },
        MkdnYankAnchorLink = { 'n', 'yaa' },
        MkdnYankFileAnchorLink = { 'n', 'yfa' },
        MkdnNextHeading = { 'n', ']]' },
        MkdnPrevHeading = { 'n', '[[' },
        MkdnIncreaseHeading = { { 'n', 'v' }, '+' },
        MkdnDecreaseHeading = { { 'n', 'v' }, '-' },
        MkdnIncreaseHeadingOp = { { 'n', 'v' }, 'g+' },
        MkdnDecreaseHeadingOp = { { 'n', 'v' }, 'g-' },
        MkdnToggleToDo = { { 'n', 'v' }, '<C-Space>' },
        MkdnNewListItem = false,
        MkdnNewListItemBelowInsert = { 'n', 'o' },
        MkdnNewListItemAboveInsert = { 'n', 'O' },
        MkdnExtendList = false,
        MkdnUpdateNumbering = { 'n', '<leader>nn' },
        MkdnTableNextCell = { 'i', '<Tab>' },
        MkdnTablePrevCell = { 'i', '<S-Tab>' },
        MkdnTableNextRow = false,
        MkdnTablePrevRow = { 'i', '<M-CR>' },
        MkdnTableNewRowBelow = { 'n', '<leader>ir' },
        MkdnTableNewRowAbove = { 'n', '<leader>iR' },
        MkdnTableNewColAfter = { 'n', '<leader>ic' },
        MkdnTableNewColBefore = { 'n', '<leader>iC' },
        MkdnTableDeleteRow = { 'n', '<leader>dr' },
        MkdnTableDeleteCol = { 'n', '<leader>dc' },
        MkdnFoldSection = { 'n', '<leader>f' },
        MkdnUnfoldSection = { 'n', '<leader>F' },
        MkdnTab = false,
        MkdnSTab = false,
        MkdnIndentListItem = { 'i', '<C-t>' },
        MkdnDedentListItem = { 'i', '<C-d>' },
        MkdnCreateLink = false,
        MkdnCreateLinkFromClipboard = { { 'n', 'v' }, '<leader>p' },
    },
}

require('mkdnflow').setup({
    modules = {
        bib = true,
        buffers = true,
        conceal = true,
        cursor = true,
        folds = true,
        foldtext = true,
        links = true,
        lists = true,
        maps = true,
        paths = true,
        tables = true,
        to_do = true,
        yaml = false,
        cmp = false,
    }
})

require('mkdnflow').setup({
    create_dirs = true,
})

require('mkdnflow').setup({
    path_resolution = {
        primary = 'first',
        fallback = 'current',
        root_marker = false,
        sync_cwd = false,
        update_on_navigate = false,
    },
})

require('mkdnflow').setup({
    filetypes = {
        markdown = true,
        rmd = true,
    },
})

require('mkdnflow').setup({
    wrap = false,
})

require('mkdnflow').setup({
    bib = {
        default_path = nil,
        find_in_root = true,
    },
})

require('mkdnflow').setup({
    silent = false,
})

require('mkdnflow').setup({
    cursor = {
        jump_patterns = nil,
    },
})

require('mkdnflow').setup({
    links = {
        style = 'markdown',
        compact = false,
        conceal = false,
        search_range = 0,
        implicit_extension = nil,
        transform_on_follow = false,
        transform_on_create = function(text)
            text = text:gsub(" ", "-")
            text = text:lower()
            text = os.date('%Y-%m-%d_') .. text
            return(text)
        end,
        auto_create = true,
        on_create_new = false,
    },
})

require('mkdnflow').setup({
    links = {
        -- If you want all link paths to be explicitly prefixed with the year
        -- and for the path to be converted to uppercase:
        transform_on_create = function(input)
            return(string.upper(os.date('%Y-')..input))
        end,
        -- Link paths that match a date pattern can be opened in a `journals`
        -- subdirectory of your notebook, and all others can be opened in a
        -- `pages` subdirectory:
        transform_on_follow = function(input)
            if input:match('%d%d%d%d%-%d%d%-%d%d') then
                return('journals/'..input)
            else
                return('pages/'..input)
            end
        end
    }
})

require('mkdnflow').setup({
    links = {
        on_create_new = function(path, title)
            -- Let zk create the note with its own templates and ID scheme.
            -- `zk new` prints the created path to stdout.
            local dir = vim.fn.fnamemodify(path, ':h')
            local cmd = { 'zk', 'new', '--no-input', '--print-path', dir }
            if title then
                table.insert(cmd, '--title')
                table.insert(cmd, title)
            end
            local result = vim.fn.system(cmd)
            local new_path = vim.trim(result)
            if vim.v.shell_error ~= 0 then
                vim.notify('zk new failed: ' .. result, vim.log.levels.ERROR)
                return nil
            end
            return new_path  -- mkdnflow opens the zk-created file
        end,
    },
})

require('mkdnflow').setup({
    new_file_template = {
        enabled = false,
        placeholders = {
            before = { title = 'link_title', date = 'os_date' },
            after = {},
        },
        template = '# {{ title }}',
    },
})

require('mkdnflow').setup({
    to_do = {
        highlight = false,
        status_propagation = { up = true, down = true },
        sort = {
            on_status_change = false,
            recursive = false,
            cursor_behavior = { track = true },
        },
        statuses = { ... },  -- See full default in docs
    },
})

require('mkdnflow').setup({
    foldtext = {
        object_count = true,
        object_count_icon_set = 'emoji',
        object_count_opts = function()
            return require('mkdnflow').foldtext.default_count_opts()
        end,
        line_count = true,
        line_percentage = true,
        word_count = false,
        title_transformer = function()
            return require('mkdnflow').foldtext.default_title_transformer
        end,
        fill_chars = {
            left_edge = '⢾⣿⣿',
            right_edge = '⣿⣿⡷',
            item_separator = ' · ',
            section_separator = ' ⣹⣿⣏ ',
            left_inside = ' ⣹',
            right_inside = '⣏ ',
            middle = '⣿',
        },
    },
})

-- SAMPLE FOLDTEXT CONFIGURATION RECIPE WITH COMMENTS
require('mkdnflow').setup({
    foldtext = {
        title_transformer = function()
            local function my_title_transformer(text)
                local updated_title = text:gsub('%b{}', '')
                updated_title = updated_title:gsub('^%s*', '')
                updated_title = updated_title:gsub('%s*$', '')
                updated_title = updated_title:gsub('^######', '░░░░░▓')
                updated_title = updated_title:gsub('^#####', '░░░░▓▓')
                updated_title = updated_title:gsub('^####', '░░░▓▓▓')
                updated_title = updated_title:gsub('^###', '░░▓▓▓▓')
                updated_title = updated_title:gsub('^##', '░▓▓▓▓▓')
                updated_title = updated_title:gsub('^#', '▓▓▓▓▓▓')
                return updated_title
            end
            return my_title_transformer
        end,
        object_count_icon_set = 'nerdfont',
        object_count_opts = function()
            local opts = {
                link = false,
                blockquote = {
                    icon = ' ',
                    count_method = {
                        pattern = { '^>.+$' },
                        tally = 'blocks',
                    }
                },
                fncblk = { icon = ' ' }
            }
            return opts
        end,
        line_count = false,
        word_count = true,
        fill_chars = {
            left_edge = '╾─🖿 ─',
            right_edge = '──╼',
            item_separator = ' · ',
            section_separator = ' // ',
            left_inside = ' ┝',
            right_inside = '┥ ',
            middle = '─',
        },
    },
})

require('mkdnflow').setup({
    tables = {
        type = 'pipe',
        trim_whitespace = true,
        format_on_move = true,
        auto_extend_rows = false,
        auto_extend_cols = false,
        style = {
            cell_padding = 1,
            separator_padding = 1,
            outer_pipes = true,
            apply_alignment = true,
        },
    },
})

require('mkdnflow').setup({
    yaml = {
        bib = { override = false },
    },
})

require('mkdnflow').setup({
    mappings = {
        MkdnEnter = { { 'n', 'v' }, '<CR>' },
        MkdnGoBack = { 'n', '<BS>' },
        MkdnGoForward = { 'n', '<Del>' },
        MkdnMoveSource = { 'n', '<F2>' },
        MkdnNextLink = { 'n', '<Tab>' },
        MkdnPrevLink = { 'n', '<S-Tab>' },
        MkdnFollowLink = false,
        MkdnDestroyLink = { 'n', '<M-CR>' },
        MkdnTagSpan = { 'v', '<M-CR>' },
        MkdnYankAnchorLink = { 'n', 'yaa' },
        MkdnYankFileAnchorLink = { 'n', 'yfa' },
        MkdnNextHeading = { 'n', ']]' },
        MkdnPrevHeading = { 'n', '[[' },
        MkdnIncreaseHeading = { { 'n', 'v' }, '+' },
        MkdnDecreaseHeading = { { 'n', 'v' }, '-' },
        MkdnIncreaseHeadingOp = { { 'n', 'v' }, 'g+' },
        MkdnDecreaseHeadingOp = { { 'n', 'v' }, 'g-' },
        MkdnToggleToDo = { { 'n', 'v' }, '<C-Space>' },
        MkdnNewListItem = false,
        MkdnNewListItemBelowInsert = { 'n', 'o' },
        MkdnNewListItemAboveInsert = { 'n', 'O' },
        MkdnExtendList = false,
        MkdnUpdateNumbering = { 'n', '<leader>nn' },
        MkdnTableNextCell = { 'i', '<Tab>' },
        MkdnTablePrevCell = { 'i', '<S-Tab>' },
        MkdnTableNextRow = false,
        MkdnTablePrevRow = { 'i', '<M-CR>' },
        MkdnTableNewRowBelow = { 'n', '<leader>ir' },
        MkdnTableNewRowAbove = { 'n', '<leader>iR' },
        MkdnTableNewColAfter = { 'n', '<leader>ic' },
        MkdnTableNewColBefore = { 'n', '<leader>iC' },
        MkdnTableDeleteRow = { 'n', '<leader>dr' },
        MkdnTableDeleteCol = { 'n', '<leader>dc' },
        MkdnTableAlignLeft = { 'n', '<leader>al' },
        MkdnTableAlignRight = { 'n', '<leader>ar' },
        MkdnTableAlignCenter = { 'n', '<leader>ac' },
        MkdnTableAlignDefault = { 'n', '<leader>ax' },
        MkdnFoldSection = { 'n', '<leader>f' },
        MkdnUnfoldSection = { 'n', '<leader>F' },
        MkdnTab = false,
        MkdnSTab = false,
        MkdnIndentListItem = { 'i', '<C-t>' },
        MkdnDedentListItem = { 'i', '<C-d>' },
        MkdnCreateLink = false,
        MkdnCreateLinkFromClipboard = { { 'n', 'v' }, '<leader>p' },
    },
})

See descriptions of commands and mappings below.

Note: <command> should be the name of a command defined in mkdnflow.nvim/plugin/mkdnflow.lua (see :h Mkdnflow-commands for a list).

To enable completion via cmp using the provided source, add mkdnflow as a source in your cmp setup function. You may also want to modify the formatting to see which completions are coming from Mkdnflow:

cmp.setup({
    -- Add 'mkdnflow' as a completion source
    sources = cmp.config.sources({
        { name = 'mkdnflow' },
    }),
    -- Completion source attribution
    formatting = {
        format = function(entry, vim_item)
            vim_item.menu = ({
                -- Other attributions
                mkdnflow = '[Mkdnflow]',
            })[entry.source_name]
            return vim_item
        end
    }
})

Below are descriptions of the user commands defined by Mkdnflow. For the default mappings to these commands, see the mappings = ... section of Configuration options.

There are several ways to customize mkdnflow's keybindings. All mkdnflow commands (e.g., MkdnFollowLink, MkdnToggleToDo) are standard Neovim user commands and can be mapped using any method you'd normally use to map a Neovim command.

To disable a single default mapping, set it to false in the mappings table:

require('mkdnflow').setup({
    mappings = {
        MkdnNextLink = false,              -- Frees <Tab>
        MkdnPrevLink = false,              -- Frees <S-Tab>
        MkdnNewListItemBelowInsert = false, -- Frees 'o'
        MkdnNewListItemAboveInsert = false, -- Frees 'O'
    },
})

To disable all default mappings at once, disable the maps module:

require('mkdnflow').setup({
    modules = { maps = false },
})

The simplest way to change a binding is to set a different key in the mappings table. Each entry takes a mode (or array of modes) and a key string:

require('mkdnflow').setup({
    mappings = {
        MkdnFollowLink = { 'n', 'gf' },         -- Single mode
        MkdnToggleToDo = { { 'n', 'v' }, 'tt' }, -- Multiple modes
        MkdnEnter = false,                       -- Disable default
    },
})

The on_attach callback fires each time mkdnflow activates on a matching buffer. It receives the buffer number as its argument, making it ideal for buffer-local mappings, options, or autocommands.

When modules.maps is enabled (the default), default mappings are set up before on_attach runs, so you can selectively override or supplement them:

require('mkdnflow').setup({
    on_attach = function(bufnr)
        local opts = { buffer = bufnr }

        -- Bind a command to an additional key
        vim.keymap.set('n', 'gf', '<Cmd>MkdnFollowLink<CR>', opts)

        -- Bind the same command in multiple modes
        vim.keymap.set({ 'n', 'v' }, 'tt', '<Cmd>MkdnToggleToDo<CR>', opts)

        -- Add a mapping not in the defaults
        vim.keymap.set('n', '<leader>ml', '<Cmd>MkdnCreateLink<CR>', opts)

        -- Delete a default mapping you don't want
        pcall(vim.keymap.del, 'n', '+', { buffer = bufnr })

        -- Set buffer-local options
        vim.bo[bufnr].textwidth = 80
    end,
})

To use on_attach as the sole source of mappings (fully manual control), disable the maps module:

require('mkdnflow').setup({
    modules = { maps = false },
    on_attach = function(bufnr)
        local opts = { buffer = bufnr }
        vim.keymap.set('n', '<CR>', '<Cmd>MkdnEnter<CR>', opts)
        vim.keymap.set('n', '<BS>', '<Cmd>MkdnGoBack<CR>', opts)
        vim.keymap.set('n', '<Tab>', '<Cmd>MkdnNextLink<CR>', opts)
        vim.keymap.set({ 'n', 'v' }, '<C-Space>', '<Cmd>MkdnToggleToDo<CR>', opts)
    end,
})

You can also use on_attach to create links in both markdown and wiki styles from different keys. The MkdnCreateLink and MkdnCreateLinkFromClipboard commands accept an optional style argument (abbreviations like w and m are accepted):

require('mkdnflow').setup({
    on_attach = function(bufnr)
        local opts = { buffer = bufnr }
        -- Markdown link from clipboard (uses configured default)
        vim.keymap.set({ 'n', 'v' }, '<leader>p',
            '<Cmd>MkdnCreateLinkFromClipboard<CR>', opts)
        -- Wiki link from clipboard (per-call style override)
        vim.keymap.set({ 'n', 'v' }, '<leader>wp',
            '<Cmd>MkdnCreateLinkFromClipboard wiki<CR>', opts)
    end,
})

If you use lazy.nvim, you can define mappings in the plugin spec's keys table. Use the ft field to scope them to markdown buffers:

{
    'jakewvincent/mkdnflow.nvim',
    ft = { 'markdown', 'rmd' },
    opts = {
        mappings = {
            MkdnFollowLink = false, -- Disable default
            MkdnEnter = false,
        },
    },
    keys = {
        { 'gf', '<Cmd>MkdnFollowLink<CR>', ft = 'markdown', desc = 'Follow link' },
        { '<CR>', '<Cmd>MkdnEnter<CR>', ft = 'markdown', desc = 'Mkdn enter' },
    },
}

You can also set mappings via your own FileType autocmd. This is equivalent to on_attach but managed outside of mkdnflow's config:

vim.api.nvim_create_autocmd('FileType', {
    pattern = { 'markdown', 'rmd' },
    callback = function(args)
        vim.keymap.set('n', 'gf', '<Cmd>MkdnFollowLink<CR>', {
            buffer = args.buf,
            desc = 'Follow link',
        })
    end,
})

Mkdnflow provides a range of Lua functions that can be called directly to manipulate markdown files, navigate through buffers, manage links, and more. Below are the primary functions available:

1. Initialization (Initialization)
2. Link management (Link management)
3. Link & path handling (Link and path handling)
4. Templates (Templates)
5. Buffer navigation (Buffer navigation)
6. Cursor movement (Cursor movement)
7. Cursor-aware manipulations (Cursor-aware manipulations)
8. List management (List management)
9. To-do list management (To-do list management)
10. Table management (Table management)
11. Folds (Folds)
12. Yaml blocks (Yaml blocks)
13. Bibliography (Bibliography)
14. Statusline components (Statusline components)

require('mkdnflow').setup(config)

Initializes the plugin with the provided configuration. See Advanced configuration and sample recipes. If called with an empty table, the default configuration is used.

• Parameters:
  • config: (table) Configuration table containing various settings such as filetypes, modules, mappings, and more.

require('mkdnflow').forceStart(opts)

Activates the plugin if it has not already been activated. This is called automatically when a buffer with a matching filetype is opened, but can be triggered manually via the :Mkdnflow command.

• Parameters:
  • opts: (table) Table of options.
    • opts[1]: (string) Pass 'silent' to suppress the startup message.

require('mkdnflow').links.createLink(args)

Creates a markdown link from the text under the cursor or visual selection.

• Parameters:
  • args: (table) Arguments to customize link creation.
    • from_clipboard: (boolean) If true, use the system clipboard content as the link source.
    • style: (string|nil) Link style override: 'markdown' or 'wiki'. Defaults to links.style from config.
    • transform_scope: (string|nil) Transform scope override: 'path' or 'filename'. Defaults to links.transform_scope from config.

require('mkdnflow').links.createFootnote(args)

Creates a footnote reference at the cursor position and a definition at the end of the document. Jumps to the definition line in insert mode.

• Parameters:
  • args: (table) Arguments to customize footnote creation.
    • label: (string|nil) If provided, uses this string as the footnote label (e.g., 'myref' creates [^myref]). If nil, auto-increments from the highest existing numeric footnote.

require('mkdnflow').links.renumberFootnotes()

Renumbers all footnote references and definitions (including string-labeled) to form a sequential integer series based on order of first appearance. Consolidates definitions under the configured heading. Warns and aborts if duplicate definitions are found.

require('mkdnflow').links.refreshFootnotes()

Refreshes footnote numbering (numeric labels only) and consolidates definitions under the configured heading in appearance order. String-labeled footnotes are preserved. Warns and aborts if duplicate definitions are found.

require('mkdnflow').links.followLink(args)

Follows the link under the cursor, opening the corresponding file, URL, or directory. Image links are opened in the system's default image viewer.

• Parameters:
  • args: (table) Arguments for following the link.
    • path: (string|nil) The path/source to follow. If nil, a path from a link under the cursor will be used.
    • anchor: (string|nil) An anchor, either one in the current buffer (in which case path will be nil), or one in the file referred to in path.
    • range: (boolean|nil) Whether a link should be created from a visual selection range. This is only relevant if create_on_follow_failure is true, there is no link under the cursor, and there is currently a visual selection that needs to be made into a link.

require('mkdnflow').links.destroyLink()

Destroys the link under the cursor, replacing it with plain text.

require('mkdnflow').links.tagSpan()

Tags a visual selection as a span, useful for adding attributes to specific text segments.

require('mkdnflow').links.getLinkUnderCursor(col)

Returns the link under the cursor at the specified column.

• Parameters:
  • col: (number|nil) The column position to check for a link. The current cursor position is used if this is not specified.

require('mkdnflow').links.getLinkPart(link_table, part)

Retrieves a specific part of a link, such as the source or the text.

• Parameters:
  • link_table: (table) The table containing link details, as provided by require('mkdnflow').links.getLinkUnderCursor().
  • part: (string|nil) The part of the link to retrieve (one of 'source', 'name', or 'anchor'). Default: 'source'.

require('mkdnflow').links.getBracketedSpanPart(part)

Retrieves a specific part of a bracketed span.

• Parameters:
  • part: (string|nil) The part of the span to retrieve (one of 'text' or 'attr'). Default: 'attr'.

require('mkdnflow').links.hasUrl(string, to_return, col)

Checks if a given string contains a URL and optionally returns the URL.

• Parameters:
  • string: (string) The string to check for a URL.
  • to_return: (string) The part to return (e.g., "url").
  • col: (number) The column position to check.

require('mkdnflow').links.transformPath(text, scope)

Transforms the given text according to the default or user-supplied explicit transformation function.

• Parameters:
  • text: (string) The text to transform.
  • scope: (string|nil) Transform scope: 'path' (transform entire text) or 'filename' (transform only the filename portion after the last /). Defaults to links.transform_scope from config.

require('mkdnflow').links.formatLink(text, source, part, style, transform_scope)

Creates a formatted link with whatever is provided.

• Parameters:
  • text: (string) The link text.
  • source: (string) The link source.
  • part: (integer|nil) The specific part of the link to return.
    • nil: () Return the entire link.
    • 1: () Return the text part of the link.
    • 2: () Return the source part of the link.
  • style: (string|nil) Link style override: 'markdown' or 'wiki'. Defaults to links.style from config.
  • transform_scope: (string|nil) Transform scope override: 'path' or 'filename'. Defaults to links.transform_scope from config.

require('mkdnflow').paths.moveSource()

Moves the source file of a link to a new location, updating the link accordingly.

require('mkdnflow').paths.handlePath(path, anchor)

Handles all 'following' behavior for a given path, potentially opening it or performing other actions based on the type.

• Parameters:
  • path: (string) The path to handle.
  • anchor: (string|nil) Optional anchor within the path.

require('mkdnflow').paths.formatTemplate(timing, template)

Deprecated: Use require('mkdnflow').templates.formatTemplate() instead. This function is a backward-compatible shim that delegates to the templates module. It will be removed in a future major version.

• Parameters:
  • timing: (string) "before" or "after" specifying when to perform the formatting.
  • template: (string|nil) The template to format. If not provided, the default new file template is used.

require('mkdnflow').paths.updateDirs()

Updates the working directory after switching notebooks or notebook folders (if nvim_wd_heel is true).

require('mkdnflow').paths.pathType(path, anchor, link_type)

Determines the type of the given path. Returns 'external' for image links, file:-prefixed paths, and paths with non-notebook file extensions (e.g. .pdf, .docx); 'url' for web URLs; 'citation' for @-prefixed paths; 'anchor' for same-page anchors; 'nb_page' for notebook pages (extensionless paths or paths with a notebook extension like .md); or nil if no path is provided.

• Parameters:
  • path: (string) The path to check.
  • anchor: (string|nil) Optional anchor within the path.
  • link_type: (string|nil) The link type from the parser (e.g. 'image_link').

require('mkdnflow').paths.transformPath(path)

Transforms the given path based on the plugin's configuration and transformations.

• Parameters:
  • path: (string) The path to transform.

require('mkdnflow').templates.formatTemplate(timing, template, opts)

Formats the new file template by resolving all placeholders in a single pass. Function placeholders receive a ctx table with resolved built-in values: link_title, os_date, source_file, filename, and heading_context.

• Parameters:
  • timing: (string|nil) Kept for API compatibility; no longer affects behavior. Previously distinguished "before" and "after" buffer creation.
  • template: (string|nil) The template to format. If not provided, the default new file template is used.
  • opts: (table|nil) Optional parameters.
    • target_path: (string|nil) The path of the new file being created. Used to derive the filename field in the ctx table. If not provided, the current buffer name is used as fallback.

require('mkdnflow').templates.apply(template)

Injects a formatted template string into the current buffer (replacing all content). This is typically called after a new file buffer has been opened.

• Parameters:
  • template: (string) The template string produced by formatTemplate().

require('mkdnflow').buffers.goBack()

Navigates to the previously opened buffer.

require('mkdnflow').buffers.goForward()

Navigates to the next buffer in the history.

require('mkdnflow').cursor.goTo(pattern, reverse)

Moves the cursor to the next or previous occurrence of the specified pattern.

• Parameters:
  • pattern: (string|table) The Lua regex pattern(s) to search for.
  • reverse: (boolean) If true, search backward.

require('mkdnflow').cursor.goTo("%[.*%](.*)", false) -- Go to next markdown link

require('mkdnflow').cursor.toNextLink()

Moves the cursor to the next link in the file.

require('mkdnflow').cursor.toPrevLink()

Moves the cursor to the previous link in the file.

require('mkdnflow').cursor.toHeading(anchor_text, reverse)

Moves the cursor to the specified heading.

• Parameters:
  • anchor_text: (string|nil) The text of the heading to move to, transformed in the way that is expected for an anchor link to a heading. If nil, the function will go to the next closest heading.
  • reverse: (boolean) If true, search backward.

require('mkdnflow').cursor.toId(id, starting_row)

Moves the cursor to the specified ID in the file.

• Parameters:
  • id: (string) The Pandoc-style ID attribute (in a tagged span) to move to.
  • starting_row: (number|nil) The row to start the search from. If not provided, the cursor row will be used.

require('mkdnflow').cursor.changeHeadingLevel(change)

Increases or decreases the importance of the heading under the cursor by adjusting the number of hash symbols.

• Parameters:
  • change: (string) "increase" to decrease hash symbols (increasing importance), "decrease" to add hash symbols, decreasing importance.

require('mkdnflow').cursor.yankAsAnchorLink(full_path)

Yanks the current line as an anchor link, optionally including the file path (relative to the path resolution base) depending on the value of the argument.

• Parameters:
  • full_path: (boolean) If true, includes the file path relative to the configured path resolution base.

require('mkdnflow').lists.newListItem({ carry, above, cursor_moves, mode_after, alt })

Inserts a new list item with various customization options such as whether to carry content from the current line, position the new item above or below, and the editor mode after insertion.

• Parameters:
  • carry: (boolean) Whether to carry content following the cursor on the current line into the new line/list item.
  • above: (boolean) Whether to insert the new item above the current line.
  • cursor_moves: (boolean) Whether the cursor should move to the new line.
  • mode_after: (string) The mode to enter after insertion ("i" for insert, "n" for normal).
  • alt: (string) Which key(s) to feed if this is called while the cursor is not on a line with a list item. Must be a valid string for the first argument of vim.api.nvim_feedkeys.

require('mkdnflow').lists.hasListType(line)

Checks if the given line is part of a list.

• Parameters:
  • line: (string) The (content of the) line to check. If not provided, the current cursor line will be used.

require('mkdnflow').lists.toggleToDo(opts)

Toggles (rotates) the status of a to-do list item based on the provided options.

• Parameters:
  • opts: (table) Options for toggling.

require('mkdnflow').lists.updateNumbering(opts, offset)

Updates the numbering of the list items in the current list.

• Parameters:
  • opts: (table) Options for updating numbering.
    • opts[1]: (integer) The number to start the current ordered list with.
  • offset: (number) The offset to start numbering from. Defaults to 0 if not provided.

require('mkdnflow').to_do.toggle_to_do()

Toggle (rotate) to-do statuses for a to-do item under the cursor.

require('mkdnflow').to_do.get_to_do_item(line_nr)

Retrieves a to-do item from the specified line number.

• Parameters:
  • line_nr: (number) The line number to retrieve the to-do item from. If not provided, defaults to the cursor line number.

require('mkdnflow').to_do.get_to_do_list(line_nr)

Retrieves the entire to-do list of which the specified line number is an item/member.

• Parameters:
  • line_nr: (number) The line number to retrieve the to-do list from. If not provided, defaults to the cursor line number.

require('mkdnflow').to_do.hl.init()

Initializes highlighting for to-do items. If highlighting is enabled in your configuration, you should never need to use this.

require('mkdnflow').tables.formatTable()

Formats the current table, ensuring proper alignment and spacing.

require('mkdnflow').tables.addRow(offset)

Adds a new row to the table at the specified offset.

• Parameters:
  • offset: (number) The position (relative to the current cursor row) in which to insert the new row. Defaults to 0, in which case a new row is added beneath the current cursor row. An offset of -1 will result in a row being inserted above the current cursor row; an offset of 1 will result in a row being inserted after the row following the current cursor row; etc.

require('mkdnflow').tables.addCol(offset)

Adds a new column to the table at the specified offset.

• Parameters:
  • offset: (number) The position (relative to the table column the cursor is currently in) to insert the new column. Defaults to 0, in which case a new column is added after the current cursor table column. An offset of -1 will result in a column being inserted before the current cursor table column; an offset of 1 will result in a column being inserted after the column following the current cursor table column; etc.

require('mkdnflow').tables.newTable(opts)

Creates a new table with the specified options.

• Parameters:
  • opts: (table) Options for the new table (number of columns and rows).
    • opts[1]: (integer) The number of columns the table should have
    • opts[2]: (integer) The number of rows the table should have (excluding the header row)
    • opts[3]: (string) Whether to include a header for the table or not ('noh' or 'noheader': Don't include a header row; nil: Include a header)

require('mkdnflow').tables.alignCol(alignment)

Sets the alignment of the table column under the cursor and reformats the table. Works with both pipe tables and Pandoc grid tables.

• Parameters:
  • alignment: (string) The alignment to set for the column. One of 'left', 'right', 'center', or 'default'.

require('mkdnflow').tables.pasteTable(opts)

Pastes delimited data from the system clipboard as a formatted markdown table, inserted below the current cursor line. Auto-detects the delimiter unless one is specified.

• Parameters:
  • opts: (table) Options for pasting.
    • delimiter: (string|nil) The delimiter character to use. If nil, the delimiter is auto-detected from the clipboard content. Supported delimiters: tab, comma, semicolon, pipe.
    • header: (boolean) Whether to treat the first row as a header and insert a separator row after it. Default: true.

require('mkdnflow').tables.tableFromSelection(line1, line2, opts)

Converts visually-selected delimited lines into a formatted markdown table, replacing the selected lines. Auto-detects the delimiter unless one is specified. Supports CSV, TSV, and other delimited formats including RFC 4180-style quoted fields.

• Parameters:
  • line1: (integer) The start line of the selection (1-indexed).
  • line2: (integer) The end line of the selection (1-indexed).
  • opts: (table) Options for conversion.
    • delimiter: (string|nil) The delimiter character to use. If nil, the delimiter is auto-detected. Supported delimiters: tab, comma, semicolon, pipe.
    • header: (boolean) Whether to treat the first row as a header and insert a separator row after it. Default: true.

require('mkdnflow').tables.isPartOfTable(text, linenr)

Guesses as to whether the specified text is part of a table.

• Parameters:
  • text: (string) The content to check for table membership.
  • linenr: (number) The line number corresponding to the text passed in.

require('mkdnflow').tables.moveToCell(row_offset, cell_offset)

Moves the cursor to the specified cell in the table.

• Parameters:
  • row_offset: (number) The difference between the current row and the target row. 0, for instance, will target the current row.
  • cell_offset: (number) The difference between the current table column and the target table column. 0, for instance, will target the current column.

require('mkdnflow').folds.getHeadingLevel(line)

Gets the heading level of the specified line.

• Parameters:
  • line: (string) The line content to get the heading level for. Required.

require('mkdnflow').folds.foldSection()

Folds the current section based on markdown headings.

require('mkdnflow').folds.unfoldSection()

Unfolds the current section.

require('mkdnflow').yaml.hasYaml()

Checks if the current buffer contains a YAML header block.

require('mkdnflow').yaml.ingestYamlBlock(start, finish)

Parses and ingests a YAML block from the specified range.

• Parameters:
  • start: (number) The starting line number.
  • finish: (number) The ending line number.

require('mkdnflow').bib.handleCitation(citation)

Handles a citation, potentially linking to a bibliography entry or external source.

• Parameters:
  • citation: (string) The citation key to handle. Required.

The following functions are designed for use in statusline, winbar, or tabline components. They return information about the plugin's current state and are safe to call frequently (e.g. on every statusline redraw).

require('mkdnflow').getNotebook()

Returns information about the current notebook (root directory), or nil if no root is active (e.g. when path_resolution.primary is not 'root', or no root marker was found). Designed for use in statusline, winbar, or tabline components.

Example: lualine component

require('lualine').setup({
    sections = {
        lualine_x = {
            {
                function()
                    local nb = require('mkdnflow').getNotebook()
                    return nb and nb.name or ''
                end,
                cond = function()
                    return require('mkdnflow').getNotebook() ~= nil
                end,
            },
        },
    },
})

Example: custom statusline

vim.o.statusline = '%f %m%=%{%v:lua.require("mkdnflow").getNotebook() '
    .. '~= nil and " " .. require("mkdnflow").getNotebook().name or ""%}'

See CONTRIBUTING.md

Mkdnflow uses Semantic Versioning. Version numbers follow the format MAJOR.MINOR.PATCH:

• MAJOR: Incompatible API or configuration changes
• MINOR: New functionality in a backward-compatible manner
• PATCH: Backward-compatible bug fixes

For a detailed history of changes, see CHANGELOG.md.

• obsidian.nvim
• wiki.vim
• Neorg
• markdown.nvim
• Vimwiki
• follow-md-links.nvim

• Obsidian.md
• clipboard-image.nvim
• mdeval.nvim
• In-editor rendering
  • render-markdown.nvim
  • markview.nvim
• Preview plugins
  • Markdown Preview for (Neo)vim
  • nvim-markdown-preview
  • glow.nvim
  • auto-pandoc.nvim