markdown-literate

EARLY STAGES PLUGIN: please use with care, as this is very early stages and should not be relied for everyday workflow just yet. There may be some bugs still around in the code base.

Scope for this project:

This plugin in combination with the marksman plugin for Neovim LSP is intended to be a full experience to be able to write full literate programs spanning over multiple files and directories.

Initial goals to implement

• Tangle markdown codeblocks on a per-codeblock basis
  • The expected syntax for doing this is as follows: <language> { tangle: path/to/file.lang }.
  • The above syntax should be used at the start of the node.
• Remove/untangle all tangled files in the project
  • For a full project scope/directory
• Edit a code block with its native LSP in a new buffer or popup window.
  • Implement customised options for the user to use window decorations, window position
• Setup custom keymaps for each of the events.
  • Integrate a configuration for this rather then calling functions directly
• Tangle multiple markdown files that are found under a project.
  • Should find all markdown files in the directory, using some identifier as the root dir
  • edit: Implementation is based on the cwd of the current neovim instance, you can use a plugin like vim-rooter to ensure that we are relative to a specific directory.
• Ability to tangle an entire *.md file to a single document without specifying files
  • Should check if all code blocks are the same language,
  • Create a target directory of all source files using the *.md as the base name for the file

Usage

Installing with packer.nvim and using the default keybindings, see Setup and Customisation to setup your own keymaps for this plugin.

use({
  "atidyshirt/markdown-literate",
  config = function()
    require("markdown-literate").setup()
  end,
})

The default keymaps are as follows:

Keymap	Purpose
<leader>tf	Tangle the current markdown file
<leader>tw	Tangle the workspaces markdown files
<leader>tu	Undo/remove all tangled files
<leader>te	Edit a code block using LSP

Current Issues

• Currently the first time you write to the edit buffer, you will need to force write using :w!, this is an issue to fix in the future.
• Currently we must specify tangle locations (see the goals of this plugin)

Documentation

• Setup and Customisation
• Example of code block syntax