jpoppe / mkdnflow.nvim Goto Github PK

Features / Installation / Starting a notebook / Config / Commands & mappings / To do / Recent changes / Links

This plugin is designed for the fluent navigation of notebooks (AKA "wikis") written in markdown. It is a set of functions and mappings to those functions which make it easy to navigate and manipulate markdown notebooks in Neovim. The original goal of Mkdnflow was to replicate some features from Vimwiki in Lua instead of Vimscript, but my current goal for this project is to make this plugin as useful as possible for anyone using Neovim who maintains a set of markdown notes and wishes to efficiently navigate those notes and keep them organized and connected.

I keep tabs on the project's issues and appreciate feature requests, suggestions, and bug reports. If you'd like to contribute to the plugin, fork this repo and submit a pull request with your changes or additions. If you need Lua resources, see this page for a starting point or run :h lua or :h api in Neovim.

• Linux, macOS, or Windows
• Neovim >= 0.7.0 for all functionality (most will work with Neovim >= 0.5.0, but mappings will need to be set separately)
• (Optional: If you wish to use custom UTF-8 symbols as your to-do symbols, you'll need the luarocks module luautf8. Luarocks dependencies can be installed via Packer.)

• Vimwiki doesn't use markdown by default; mkdnflow only works for markdown.
• I'm intending mkdnflow to be a little lighter weight/less involved than Vimwiki. Mkdnflow doesn't and won't provide syntax highlighting and won't create new filetypes.
• Written in Lua

• Use either markdown or wiki-link link styles by setting a config option.
• 🆕 Conceal link sources for either link type by enabling conceal in your config
  • Markdown-style links are shortened from [Link](source.md) to Link
  • Wiki-style links are shortened from [[source|Link]] to Link or from [[source]] to source
  • NOTE: If you are using the recently split treesitter parsers for markdown, you do not need to enable conceal through mkdnflow--if you are using markdown-style links. Just make sure you have markdown and markdown_inline installed and enabled in markdown filetypes, and in your .vimrc or init.lua, enable conceal (set conceallevel=2 or vim.wo.conceallevel = 2).

• <CR> on word under cursor or visual selection to create a notebook-internal link
  • 🆕 Customizable path text transformations (by default, text is converted to lowercase, spaces are converted to dashes, and the date in YYYY-MM-DD format is prefixed to the filename, separated by an underscore). See the description of the links config key for customization instructions.
• <M-CR> (Alt-Enter) when your cursor is anywhere in a link to destroy it (replace it with the text in [...])
• Create an anchor link if the visual selection starts with #
• Create a web link if what's under the cursor is a URL (and move the cursor to enter the link name)
• ya on a heading to add a formatted anchor link for the heading to the default register (ready to paste in the current buffer)
  • yfa to do the same, but adding the absolute path of the file before the anchor (for pasting in another buffer)

• <CR> on various kinds of links to "follow" them:
  • .md links open in the current window
  • Absolute links or .md links relative to home open in the current window but are interpreted with absolute perspective (e.g. [File](/home/user/file.md)/[File](C:\Users\user\file.md) on Windows, or [File](~/Documents/file.md))
  • Links to a file prefixed with file: (e.g. [My Xournal notes](file:notes.xopp)) open with the system's default program for that filetype
  • Link to URLs are opened in the default browser
  • Anchor links to headings in the current file will trigger a jump to that heading. Headings must start with a hash, and the path part of the link must look like the heading with (a) any spaces between the last hash mark and the beginning of the heading text removed, (b) all other spaces converted to a dash, (c) non-alphanumeric characters removed, (d) strings of multiple hashes converted into a single hash, and (e) all upper-case characters converted to lower-case characters. For example:
    • ## Bills to pay will be jumped to if the path in the anchor link is #bills-to-pay
    • #### Groceries/other things to buy will be jumped to if the path in the anchor link is #groceriesother-things-to-buy
  • 🆕 Following a link to a directory (e.g. another notebook) will open a dialogue for you to select which file in the directory to open in the current window
• <CR> on citations to open associated files or websites (e.g. @Chomsky1957, with or without brackets around it)
  • Specify a path to a .bib file in your config—or if perspective.priority is root, simply place your bib files to be searched in your notebook's root directory.
  • Files are prioritized. If no file is found associated with the citation key, a URL associated with it will be opened. If no URL is found, a DOI is opened. If no DOI is found, whatever is in the howpublished field is opened.
  • 🔥 Hot tip: make reaching your contacts via work messaging apps (e.g. Slack) easier by keeping a bib file that associates your contacts' messaging handles with the URL for your direct message thread with that contact. For instance, if you point the plugin to a bib file with the following entry, <CR>ing on @dschrute in a markdown document would take you to the associated Slack thread.

@misc{dschrute,
    url={https://dundermifflin.slack.com/archives/P07BFJD82}
}

• <Tab> and <S-Tab> to jump to the next and previous links in the file
  • "Wrap" to the beginning/end of the file with a config setting

• Specify what perspective the plugin-should take when interpreting links to files. There are three options:
  1. Interpret links relative to the first-opened file (default behavior; similar to #3 if your first-opened file is always in the root directory)
  2. Interpret links relative to the file open in the current buffer
  3. Interpret links relative to the root directory of the notebook that the file in the current buffer is a part of. To enable this functionality, set perspective.priority to root in your config, and pass a file as the value of perspective.root_tell. The tell is the name of a single file that can be used to identify the root directory (e.g. index.md, .git, .root, .wiki_root, etc.). See the default config for how to configure the perspective table.
  • Override any of the above settings by specifying a link to a markdown file with an absolute path (one that starts with / or ~/). Links within this file will still receive the relative interpretation, so this is best for references out of the project directory to markdown files without their own dependencies (unless those dependencies are within the project directory).
• 🆕 Keep your files organized and your links simple by customizing link interpretation using an implicit transformation function.

• If a link goes to a file in a directory that doesn't exist, it can optionally be created

• 🆕 Use built-in dialog triggered by MkdnMoveSource (mapped to <F2> by default) to rename a link's source and rename/move the linked file simultaneously
  • Perspective, implicit extensions, and custom implicit transformations are all taken into account when moving the linked file
  • The dialog will confirm the details of the changes for you to approve/reject before taking any action

• <BS> to go backward (to the previous file/buffer opened in the current window, like clicking the back button in a web browser)
• <Del> to go forward (to the subsequent file/buffer opened in the current window, like clicking the forward button in a web browser)

• Easy-to-remember default keybindings that activate only in markdown files
• Customize keybindings individually or disable them altogether)

• Increase/decrease heading levels (mapped to +/- by default). Note: Increasing the heading means increasing it in importance (i.e. making it bigger or more prominent when converted to HTML and rendered in a browser), which counterintuitively means removing a hash symbol.

• Toggle the status of a to-do list item on the current line (mapped to <C-Space> by default). Using the default settings, toggling will result in the following changes. To-do symbols can be customized (make sure to use the luautf8 luarock dependency if you want to use utf8 to-do symbols).
  • * [ ] ... → * [-] ...
  • * [-] ... → * [X] ...
  • * [X] ... → * [ ] ...
• 🆕 Toggle multiple to-do items at once by selecting the lines to toggle in (simple) visual mode (mapped to <C-Space> by default)
• 🆕 Create to-do items from plain unordered or ordered lists (mapped to <C-Space> by default)
• Automatically update any parent to-dos when child to-dos are toggled.
  • When all child to-dos have been marked complete, the parent is marked complete
  • When at least one child to-do has been marked in-progress, the parent to-do is marked in-progress
  • When a parent to-do is marked complete and one child to-do is reverted to not-yet-started or in-progress, the parent to-do is marked in-progress
  • When a parent to-do is marked complete or in-progress and all child to-dos have been reverted to not-yet-started, the parent to-do is marked not-yet-started.
• 🆕 Manually update numbering with MkdnUpdateNumbering (mapped to <leader>nn by default) or MkdnUpdateNumbering 0 if, e.g., you want to start numbering at 0
• Smart(er) behavior when <CR>ing in lists (NOTE: currently not enabled by default. See below.)
  • NOTE: The following functionality is disabled by default in case some find it intrusive. To enable the functionality, remap <CR> in insert mode (see the following code block).
  • In unordered lists: Add another bullet on the next line, unless the current list item is empty, in which case it will be erased
  • In ordered lists: Add another item on the next line (keeping numbering updated), unless the current item is empty, in which case it will be erased
  • In unordered and ordered to-do lists: Add another to-do item on the next line, unless the current to-do is empty, in which case it will be replaced with a simple (non-to-do) list item
  • 🆕 Automatically indent a new list item when the current one ends in a colon
  • 🆕 Demote empty indented list items by reducing the indentation by one level
• 🆕 Add new list items using the list type of the current line without any of the fancy stuff listed above (see MkdnExtendList)

require('mkdnflow').setup({
    mappings = {
        MkdnNewListItem = {'i', '<CR>'}
    }
})

• 🆕 Create a markdown table of x columns and y rows with :MkdnTable x y. Table headers are added automatically; to exclude headers, use :MkdnTable x y noh
• 🆕 Format existing tables with :MkdnTableFormat
• 🆕 Jump forward and backward between cells (mapped to <Tab> and <S-Tab> in insert mode by default)
• 🆕 Jump forward and backward between rows (the latter is mapped to <M-CR> in insert mode by default)
  • NOTE: No default mapping is provided for jumping to the next row. To use this functionality, specify an insert-mode mapping for either MkdnNextRow or MkdnCR in the mappings table.
• 🆕 Optionally trim extra whitespace from a cell when formatting (see config options)
• 🆕 Optionally disable formatting when moving cells
• 🆕 Add new rows or columns (before or after the current row/cell; see default mappings)

More coming soon! I use this plugin daily for work have been regularly adding new features for my use cases. Please share ideas and feature requests by creating an issue.

use({'jakewvincent/mkdnflow.nvim',
     config = function()
        require('mkdnflow').setup({
            -- Config goes here; leave blank for defaults
        })
     end
})

use({'jakewvincent/mkdnflow.nvim',
     rocks = 'luautf8',
     config = function()
        require('mkdnflow').setup({
            -- Config goes here; leave blank for defaults
        })
     end
})

require('paq')({
    -- Your other plugins;
    'jakewvincent/mkdnflow.nvim';
    -- Your other plugins;
})

-- Include the setup function somewhere else in your init.lua/vim file, or the
-- plugin won't activate itself:

require('mkdnflow').setup({
    -- Config goes here; leave blank for defaults
})

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

" NeoBundle
NeoBundle 'jakewvincent/mkdnflow.nvim'

" Vundle
Bundle 'jakewvincent/mkdnflow.nvim'

" Pathogen
git clone https://github.com/jakewvincent/mkdnflow.nvim.git ~/.vim/bundle/mkdownflow.nvim

" Dein
call dein#add('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

All functionality of the plugin should now work on all operating systems, including Windows! However, since I don't use Windows on my daily driver, there may be edge cases that cause trouble. Please file an issue if anything comes up.

As long as you successfully installed Mkdnflow, you don't need to do anything special to start using the plugin. All of the plugin's features will be enabled for any markdown file (or for any filetype you specify under the filetypes config key). If you would like to start a notebook (AKA "wiki"), first create a directory for it. If you're using Neovim in the terminal, simply enter nvim index.md and start writing. I suggest using index.md as a landing page/table of contents that contains links to all other notes in your notebook. If you use such a landing page, try setting perspective.priority in your Mkdnflow config to 'root' and your perspective.root_tell to 'index.md' so that Mkdnflow can identify your notebook's root directory and reliably interpret links relative to this directory.

Currently, the setup function uses the defaults shown below. See the descriptions and non-default options in the section below the following block. To use these defaults, simply pass an empty table to the setup function: require('mkdnflow').setup({}). To change these settings, specify new values for any of them them in the setup function.

-- ** DEFAULT SETTINGS; TO USE THESE, PASS AN EMPTY TABLE TO THE SETUP FUNCTION **
require('mkdnflow').setup({
    filetypes = {md = true, rmd = true, markdown = true},
    create_dirs = true,             
    perspective = {
        priority = 'first',
        fallback = 'current',
        root_tell = false,
        nvim_wd_heel = true
    },    
    wrap = false,
    bib = {
        default_path = nil,
        find_in_root = true
    },
    silent = false,
    links = {
        style = 'markdown',
        conceal = false,
        implicit_extension = nil,
        transform_implicit = false,
        transform_explicit = function(text)
            text = text:gsub(" ", "-")
            text = text:lower()
            text = os.date('%Y-%m-%d_')..text
            return(text)
        end
    },
    to_do = {
        symbols = {' ', '-', 'X'},
        update_parents = true,
        not_started = ' ',
        in_progress = '-',
        complete = 'X'
    },
    tables = {
        trim_whitespace = true,
        format_on_move = true
    },
    use_mappings_table = true,
    mappings = {
        MkdnNextLink = {'n', '<Tab>'},
        MkdnPrevLink = {'n', '<S-Tab>'},
        MkdnNextHeading = {'n', '<leader>]'},
        MkdnPrevHeading = {'n', '<leader>['},
        MkdnGoBack = {'n', '<BS>'},
        MkdnGoForward = {'n', '<Del>'},
        MkdnFollowLink = {{'n', 'v'}, '<CR>'},
        MkdnDestroyLink = {'n', '<M-CR>'},
        MkdnMoveSource = {'n', '<F2>'},
        MkdnYankAnchorLink = {'n', 'ya'},
        MkdnYankFileAnchorLink = {'n', 'yfa'},
        MkdnIncreaseHeading = {'n', '+'},
        MkdnDecreaseHeading = {'n', '-'},
        MkdnToggleToDo = {{'n', 'v'}, '<C-Space>'},
        MkdnNewListItem = false,
        MkdnExtendList = false,
        MkdnUpdateNumbering = {'n', '<leader>nn'},
        MkdnTableNextCell = {'i', '<Tab>'},
        MkdnTablePrevCell = {'i', '<S-Tab>'},
        MkdnTableNextRow = false,
        MkdnTablePrevRow = {'i', '<M-CR>'},
        MkdnTableNewRowBelow = {{'n', 'i'}, '<leader>ir'},
        MkdnTableNewRowAbove = {{'n', 'i'}, '<leader>iR'},
        MkdnTableNewColAfter = {{'n', 'i'}, '<leader>ic'},
        MkdnTableNewColBefore = {{'n', 'i'}, '<leader>iC'},
        MkdnCR = false,
        MkdnTab = false,
        MkdnSTab = false
    }
})

• true: Directories referenced in a link will be (recursively) created if they do not exist
• false No action will be taken when directories referenced in a link do not exist. Neovim will open a new file, but you will get an error when you attempt to write the file.

• perspective.priority (string): Specifies the priority perspective to take when interpreting link paths
  • 'first': Links will be interpreted relative to the first-opened file (when the current instance of Neovim was started)
  • 'current': Links will be interpreted relative to the current file
  • 'root': Links will be interpreted relative to the root directory of the current notebook (requires perspective.root_tell to be specified)
  • 'nvim_wd_heel': Changes in perspective will be reflected in the nvim working directory. (In other words, the working directory will "heel" to the plugin's perspective.) This helps ensure (at least) that path completions (if using a completion plugin with support for paths) will be accurate and usable.
• perspective.fallback (string): Specifies the backup perspective to take if priority isn't possible (e.g. if it is 'root' but no root directory is found)
  • 'first': (see above)
  • 'current': (see above)
  • 'root': (see above)
• perspective.root_tell (string or boolean)
  • '<any file name>': Any arbitrary filename by which the plugin can uniquely identify the root directory of the current notebook. If false is used instead, the plugin will never search for a root directory, even if perspective.priority is set to root.

• <any arbitrary filetype extension> (boolean value)
  • true: A matching extension will enable the plugin's functionality for a file with that extension

Note: This functionality references the file's extension. It does not rely on Neovim's filetype recognition. The extension must be provided in lower case because the plugin converts file names to lowercase. Any arbitrary extension can be supplied. Setting an extension to false is the same as not including it in the list.

• true: When jumping to next/previous links or headings, the cursor will continue searching at the beginning/end of the file
• false: When jumping to next/previous links or headings, the cursor will stop searching at the end/beginning of the file

• bib.default_path (string or nil): Specifies a path to a default .bib file to look for citation keys in (need not be in root directory of notebook)
• bib.find_in_root (boolean)
  • true: When perspective.priority is also set to root (and a root directory was found), the plugin will search for bib files to reference in the notebook's top-level directory. If bib.default_path is also specified, the default path will be appended to the list of bib files found in the top level directory so that it will also be searched.
  • false: The notebook's root directory will not be searched for bib files.

• true: The plugin will not display any messages in the console except compatibility warnings related to your config
• false: The plugin will display messages to the console (all messages from the plugin start with ⬇️ )

• links.style (string)
  • 'markdown': Links will be expected in the standard markdown format: [<title>](<source>)
  • 'wiki': Links will be expected in the unofficial wiki-link style, specifically the title-after-pipe format: [[<source>|<title>]].
• links.conceal (boolean)
  • true: Link sources and delimiters will be concealed (depending on which link style is selected)
  • false: Link sources and delimiters will not be concealed by mkdnflow
• links.implicit_extension (string)
  • <any extension>: A string that instructs the plugin (a) how to interpret links to files that do not have an extension, and (b) that new links should be created without an explicit extension
• links.transform_explicit (function or false): A function that transforms the text to be inserted as the source/path of a link when a link is created. Anchor links are not currently customizable. If you want all link paths to be explicitly prefixed with the year, for instance, and for the path to be converted to uppercase, you could provide the following function under this key. (FYI: The previous functionality specified under the prefix key has been migrated here to provide greater flexibility.)

function(input)
    return(string.upper(os.date('%Y-')..input))
end

• links.transform_implicit (function or false): A function that transforms the path of a link immediately before interpretation. It does not transform the actual text in the buffer but can be used to modify link interpretation. For instance, 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, using the following function:

function(input)
    if input:match('%d%d%d%d%-%d%d%-%d%d') then
        return('journals/'..input)
    else
        return('pages/'..input)
    end
end

• to_do.symbols (array-like table): A list of symbols (each no more than one character) that represent to-do list completion statuses. MkdnToggleToDo references these when toggling the status of a to-do item. Three are expected: one representing not-yet-started to-dos (default: ' '), one representing in-progress to-dos (default: -), and one representing complete to-dos (default: X).
  • NOTE: Lua support for UTF-8 characters is limited, so some functionality will be limited if you supply UTF-8 characters as to-do symbols until I implement a workaround.
• to_do.update_parents (boolean): Whether parent to-dos' statuses should be updated based on child to-do status changes performed via MkdnToggleToDo
  • true (default): Parent to-do statuses will be inferred and automatically updated when a child to-do's status is changed
  • false: To-do items can be toggled, but parent to-do statuses (if any) will not be automatically changed
• The following entries can be used to stipulate which symbols shall be used when updating a parent to-do's status when a child to-do's status is changed. These are not required: if to_do.symbols is customized but these options are not provided, the plugin will attempt to infer what the meanings of the symbols in your list are by their order. For example, if you set to_do.symbols as {' ', '⧖', '✓'}, ' ' will be assiged to to_do.not_started, '⧖' will be assigned to to_do.in_progress, etc. If more than three symbols are specified, the first will be used as not_started, the second will be used as in_progress, and the last will be used as complete. If two symbols are provided (e.g. ' ', '✓'), the first will be used as both not_started and in_progress, and the second will be used as complete.
  • to_do.not_started (string): Stipulates which symbol represents a not-yet-started to-do
  • to_do.in_progress (string): Stipulates which symbol represents an in-progress to-do
  • to_do.complete (string): Stipulates which symbol represents a complete to-do

• tables.trim_whitespace (boolean): Whether extra whitespace should be trimmed from the end of a table cell when a table is formatted (default: true)
• tables.format_on_move (boolean): Whether tables should be formatted each time the cursor is moved via MkdnTable{Next/Prev}{Cell/Row} (default: true)

• true: Mappings will be defined with the help of mappings (see below), including your custom mappings (if defined in your mkdnflow config)
• false: Mappings will not be defined with the help of the mappings table, and in fact, no default mappings will be activated at all

Note: See default mappings

• mappings.<name of command> (array-like table or false)
  • mappings.<name of command>[1] string or array table representing the mode (or array of modes) that the mapping should apply in ('n', 'v', etc.)
  • mappings.<name of command>[2] string representing the keymap (e.g. '<Space>')
  • set mappings.<name of command> = false to disable default mapping without providing a custom mapping

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

I recommended turning on autowriteall in Neovim for markdown filetypes. This will ensure that changes to buffers are saved when you navigate away from that buffer, e.g. by following a link to another file. See :h awa.

-- If you have an init.lua
vim.cmd('autocmd FileType markdown set autowriteall')

" If you have an init.vim
autocmd FileType markdown set autowriteall

These default mappings can be disabled; see Configuration. Commands with no mappings trigger functions that are called by the functions with mappings, but I've given them a command name so you can use them as independent functions if you'd like to.

• The back-end function for :MkdnGoBack, require('mkdnflow').buffers.goBack(), returns a boolean indicating the success of goBack() (thanks, @pbogut!). This is useful if the user wishes to remap <BS> so that when goBack() is unsuccessful, another function is performed.
• If you are attempting to map <CR> to MkdnNewListItem or MkdnCR in insert mode but can't get it to work, try inspecting your current insert mode mappings and seeing if anything is overriding your mapping. Possible candidates are completion plugins and auto-pair plugins.
  • If using nvim-cmp, consider using using the mapping with a fallback, as shown here: cmp-mapping
  • If using an autopair plugin that automtically maps <CR> (e.g. nvim-autopairs), see if it provides a way to disable its <CR> mapping (e.g. nvim-autopairs allows you to disable that mapping by adding map_cr = false to the table passed to its setup function).

• Headings
  • Easy folding & unfolding
• Improve citation functionality
  • Add ability to stipulate a .bib file in a yaml block at the top of a markdown file

• 07/01/22: Properly handle alignment markers in tables
• 07/01/22: Add option not to format table when moving the cursor to a different cell
• 06/29/22: Conceal links
• 06/27/22: Added wrapper functions so <Tab> and <S-Tab> can be used in both tables and lists
• 06/27/22: Added functionality to add new rows and columns
• 06/17/22: Added functionality to jump rows in tables
• 06/16/22: Added functionality to format tables and jump cells in tables
• 06/11/22: Added function and command to insert tables
• 06/06/22: Extend functionality of MkdnToggleToDo so that it (a) will create a to-do item from a plain list item, and (b) can toggle multiple to-do items selected with simple visual mode
• 06/04/22: Easily rename files in links (with MkdnMoveSource, mapped to <F2> by default)
• 06/04/22: Variant of MkdnNewListItem added as MkdnExtendList
• 06/03/22: Add command and mapping for updating numbering

if not require('mkdnflow').buffers.goBack() then
  vim.cmd('Dirvish %:p')
end

• Awesome Neovim's list of (markdown) plugins
• A more granular list of Neovim plugins

• clipboard-image.nvim (Paste links to images in markdown syntax)
• mdeval.nvim (Evaluate code blocks inside markdown documents)
• Preview plugins
  • Markdown Preview for (Neo)vim ("Preview markdown on your modern browser with synchronised scrolling and flexible configuration")
  • nvim-markdown-preview ("Markdown preview in the browser using pandoc and live-server through Neovim's job-control API")
  • glow.nvim (Markdown preview using glow—render markdown in Neovim, with pizzazz!)
  • auto-pandoc.nvim ("[...] allows you to easily convert your markdown files using pandoc.")

• Vimwiki (Full-featured journal navigation/maintenance, written in Vimscript)
• wiki.vim (A lighter-weight alternative to Vimwiki, written in Vimscript)
• Neorg (A revised Org-mode for Neovim, written in Lua)
• follow-md-links.nvim (A simpler plugin for following markdown links, written in Lua)