Jump to: Installation / Features / Configuration / Commands & default mappings / To do / Recent changes / Other plugins and links
This plugin is designed to replicate the features I use most from Vimwiki, implementing them in Lua instead of VimL. It is a set of functions and keybindings (optional, but enabled by default) that make it easy to navigate and manipulate markdown notebooks/journals/wikis in Neovim.
If you have a suggestion or problem with anything, file an issue; or if you'd like to contribute, work on a fork of this repo and submit a pull request.
- Linux or macOS (for full functionality)
- Windows (for partial functionality; see Caveats/warnings)
- Neovim >= 0.5.0
➖ Differences from Vimwiki
- 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.
use({'jakewvincent/mkdnflow.nvim',
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
- Create links from (a) word under cursor or (b) visual selection (mapped to
<CR>
by default)- Automatically prefix filenames created in the above manner with the current date:
YYYY-MM-DD_<word>.md
. The prefix can be changed; see Configuration.
- Automatically prefix filenames created in the above manner with the current date:
- Jump to the next/previous link in the file, optionally wrapping to beginning/end of file (mapped to
<Tab>
and<S-Tab>
by default, respectively) - Follow links relative to the first-opened file or relative to the current file (mapped to
<CR>
by default)<CR>
ing on a link to a text file will open it in the current window (i.e.:e <filename>
)<CR>
ing on a link to a file tagged withfile:
(formerlylocal:
), e.g.[My Xournal notes](file:notes.xopp)
, will open that file with whatever the system's associated program is for that filetype (usingxdg-open
on Linux oropen
on macOS)<CR>
ing on a link to a web URL will open that link in your default browser
- Create missing directories if a link goes to a file in a directory that doesn't exist
<BS>
to go to previous file/buffer opened in the window- Enable/disable default keybindings (see Configuration)
- The plugin won't start automatically if the first-opened file is not one of the default or named extensions (see Configuration), but you can manually start the plugin with the defined command
:Mkdnflow
. - On Windows, the plugin should successfully load, but the use of certain functions will result in a message in the command line:
Function unavailable for Windows
. The functionality currently unavailable for Windows includes:- Opening local files and URLs outside of Neovim
- Following links within Neovim while
create_dirs
is enabled. If you are on Windows, you should setcreate_dirs
tofalse
and make sure that all directories you specify as part of a link already exist.
Currently, the setup function uses the defaults shown below. See the descriptions and non-default options in the comments above each setting. To use these defaults, simply call the setup function without any argument: require('mkdnflow').setup({})
. To change these settings, specify new values for any of them them in the setup function.
require('mkdnflow').setup({
-- Type: boolean. Use default mappings (see '❕Commands and default
-- mappings').
-- 'false' disables mappings
default_mappings = true,
-- Type: boolean. Create directories (recursively) if link contains a
-- missing directory.
-- 'false' prevents missing directories from being created
create_dirs = true,
-- Type: string. Navigate to links relative to the directory of the first-
-- opened file.
-- 'current' navigates links relative to currently open file
links_relative_to = 'first',
-- Type: key-value pair(s). The plugin's features are enabled only when one
-- of these filetypes is opened; otherwise, the plugin does nothing.
filetypes = {md = true, rmd = true, markdown = true},
-- Type: boolean. When true, the createLinks() function tries to evaluate
-- the string provided as the value of new_file_prefix.
-- 'false' results in the value of new_file_prefix being used as a string,
-- i.e. it is not evaluated, and the prefix will be invariant.
evaluate_prefix = true,
-- Type: string. Defines the prefix that should be used to create new links.
-- This is evaluated at the time createLink() is run, which is to say
-- that it's run whenever <CR> is pressed (under the default mappings).
-- This makes for many interesting possibilities.
new_file_prefix = [[os.date('%Y-%m-%d_')]],
-- Type: boolean. When true and Mkdnflow is searching for the next/previous
-- link in the file, it will wrap to the beginning of the file (if it's
-- reached the end) or wrap to the end of the file (if it's reached the
-- beginning during a backwards search).
wrap_to_beginning = false,
wrap_to_end = false
})
It is recommended to turn on autowriteall
in Neovim. 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.o.autowriteall = true
" If you have an init.vim
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.
Keymap | Mode | Command | Description |
---|---|---|---|
<Tab> |
n | :MkdnNextLink<CR> |
Move cursor to the beginning of the next link (if there is a next link) |
<S-Tab> |
n | :MkdnPrevLink<CR> |
Move the cursor to the beginning of the previous link (if there is one) |
<BS> |
n | :MkdnGoBack<CR> |
Open the last-active buffer in the current window |
<CR> |
n | :MkdnFollowPath<CR> |
Open the link under the cursor, creating missing directories if desired, or if there is no link under the cursor, make a link from the word under the cursor |
-- | -- | :MkdnGetPath<CR> |
With a link under the cursor, extract (and return) just the path part of it (i.e. the part in parentheses, following the brackets) |
-- | -- | :MkdnCreateLink<CR> |
Replace the word under the cursor with a link in which the word under the cursor is the name of the link |
-- | -- | :Mkdnflow<CR> |
Manually start Mkdnflow |
- The back-end function for
:MkdnGoBack
,require('mkdnflow).files.goBack()
, returns a boolean indicating the success ofgoBack()
(thanks, @pbogut!). This is useful if the user wishes to remap<BS>
so that whengoBack()
is unsuccessful, another function is performed.
- Easy forward navigation through buffers (with
<S-BS>
?) - "Undo" a link (replace link w/ the text part of the link)
- Lists
- To-do list functions & mappings
- Smart
<CR>
when in lists, etc.
- Fancy table creation & editing
- Create a table of x columns and y rows
- Add/remove columns and rows
- Horizontal and vertical navigation through tables (with
<Tab>
and<CR>
?) - Make a way for the user to define specialized tables (e.g. time sheets)
- Full compatibility with Windows
- Add a config option to wrap to the beginning of the document when navigating between links (11/08/21)
- Function to increase/decrease the level of headings
- Jump to in-file locations by
<CR>
ing on links to headings - Easily rename file in link
- Better way of dealing w/ paths to directories
- Option to open in GUI or w/ some tool in vim?
- Allow reference to absolute paths (interpret relatively [following config] if not prepended w/
~
or/
) - Allow parentheses in link names (issue #8)
- Command to add a "quick note" (add link to a specified file, e.g.
index.md
, and open the quick note)
- 11/10/21: Merged @pbogut's PR, which modifies
require('mkdnflow').files.goBack()
to return a boolean (true
ifgoBack()
succeeds;false
ifgoBack()
isn't possible). For the default mappings, this causes no change in behavior, but users who wish<BS>
to perform another function in the case thatgoBack()
fails can now usegoBack()
in the antecedent of a conditional. @pbogut's mapping, for reference:
if not require('mkdnflow').files.goBack() then
vim.cmd('Dirvish %:p')
end
- 11/08/21: Add option to wrap to beginning/end of file when jumping to next/previous link. Off by default.
- 11/01/21: Added vimdoc documentation
- 10/30/21: Added capability for manually starting the plugin with
:Mkdnflow
, addressing issue #5 - 09/23/21: Fixed issue #3
- 09/23/21: Added compatibility with macOS
- 09/21/21: Fixed issue #1. Implemented a push-down stack to better handle backwards navigation through previously-opened buffers.
- 09/19/21: Fixed issue #2. Paths with spaces can now be created.
- Plugins that would complement mkdnflow:
- 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.")
- Awesome Neovim's list of markdown plugins (a big list of plugins for Neovim)
- Vimwiki (Full-featured journal navigation/maintenance)