Mkdnflow.nvim

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/assets/logo/mkdnflow_logo_dark.png"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/assets/logo/mkdnflow_logo_light.png"> <img alt="Black mkdnflow logo in light color mode and white logo in dark color mode" src="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/assets/logo/mkdnflow_logo_light.png"> </picture> </p> <p align=center> <img src="https://img.shields.io/badge/Lua-2C2D72?style=for-the-badge&logo=lua&logoColor=white"> <img src="https://img.shields.io/badge/Markdown-000000?style=for-the-badge&logo=markdown&logoColor=white"> <img src="https://img.shields.io/badge/NeoVim-%2357A143.svg?&style=for-the-badge&logo=neovim&logoColor=white"> </p>

Contents

1. 🚀 Introduction
2. ✨ Features
3. 💾 Installation
4. ⚙️ Configuration
5. 🛠️ Commands & mappings
6. 📚 API
7. 🤝 Contributing
8. 🔢 Version information
9. 🔗 Related projects

🚀 Introduction

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).

✨ Features

🧭 Navigation

Within-buffer navigation

• [x] Jump to links
• [x] Jump to section headings

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/navigation_dark.gif"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/navigation_light.gif"> <img alt="In-buffer navigation demo" src="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/navigation_light.gif"> </picture>

Within-notebook navigation

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

🔗 Link and reference handling

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

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/links_dark.gif"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/links_light.gif"> <img alt="Link lifecycle demo" src="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/links_light.gif"> </picture>

📊 Table support

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

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/tables_dark.gif"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/tables_light.gif"> <img alt="Table workflow demo" src="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/tables_light.gif"> </picture>

📝 List support

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

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/lists_dark.gif"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/lists_light.gif"> <img alt="List management demo" src="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/lists_light.gif"> </picture>

✅ To-do list support

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

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/todo_dark.gif"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/todo_light.gif"> <img alt="To-do list demo" src="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/todo_light.gif"> </picture>

📁 File management

• [x] Simultaneous link and file renaming
• [x] As-needed directory creation

🪗 Folding

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

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/folding_dark.gif"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/folding_light.gif"> <img alt="Section folding demo" src="https://raw.githubusercontent.com/jakewvincent/mkdnflow-media/main/demos/folding_light.gif"> </picture>

🔮 Completion

• [x] Path completion
• [x] Completion of bibliography items

🧩 YAML block parsing

• [x] Specify a bibliography file in YAML front matter

🖌️ Visual enhancements

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

💾 Installation

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.

<details> <summary>Install with Lazy</summary>

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
})

</details> <details> <summary>Install with Vim-Plug</summary>

" 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

</details>

⚙️ Configuration

⚡ Quick start

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
}

🔧 Advanced configuration and sample recipes

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

<details> <summary>🔧 Complete default config</summary>

{
    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,
        completion = 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').foldtex