vim-literate-markdown

A Vim plugin to replicate a subset of Org mode's literate programming, for Markdown files.
git clone git://git.alex.balgavy.eu/vim-literate-markdown.git
Log | Files | Refs | README

README.md (2283B)

      1 # vim-literate-markdown
      2 
      3 ![Demo gif](demo.gif)
      4 
      5 ## What?
      6 
      7 This is a Vim plugin that attempts to replicate a subset of the features of Emacs' Org mode code handling.
      8 So for example, tangling the code from the current file, or executing blocks of code.
      9 For this purpose, it provides some mappings and commands for Markdown files.
     10 
     11 This plugin is a work in progress and far from complete.
     12 For more information about its features, see [`doc/literate-markdown.txt`](doc/literate-markdown.txt) (best viewed in Vim).
     13 For examples of literate programming, see [`examples/`](examples/).
     14 
     15 **Disclaimer:** this code is not extensively tested. It works for me, running Vim 8.2 in the terminal on macOS, but it's not guaranteed to work for others. It might not work in Neovim, as I don't use Neovim.
     16 
     17 ## Why?
     18 
     19 Literate programming is a great way to provide explanation about what you're doing in code.
     20 It also lets you document what you're doing without the need to follow the exact order of the code, unlike comments embedded in source code.
     21 You can e.g. lay out the overall structure of a program and then jump immediately to some specific computation.
     22 You can also write code out-of-order where that aids in explanation.
     23 Emacs handles literate programming quite well in Org mode; I didn't know about anything similar for Vim, particularly for Markdown files.
     24 So I wrote this to allow literate programming in Markdown, because in my opinion Markdown is a much more universal syntax than Org.
     25 
     26 ## Installation
     27 
     28 You can use your favorite plugin manager (I recommend [vim-plug](https://github.com/junegunn/vim-plug)).
     29 You can also use Vim's built-in package functionality (`:h packages`).
     30 
     31 There are no mappings by default, but the plugin provides `<Plug>` mappings and commands as described in `doc/literate-markdown.txt`.
     32 
     33 ## Documentation
     34 There is Vim-based documentation in doc/literate-markdown.txt.
     35 
     36 There are also examples in the `examples/` directory.
     37 
     38 This plugin itself is written in literate markdown:
     39 - `examples/literate_markdown_autoload.md`: autoload functions (the bulk of the plugin)
     40 - `examples/literate_markdown_ftplugin.md`: the interface for the user -- commands and mappings
     41 
     42 ## Tests
     43 There are tests in the `tests/` directory.
     44 Their usage is explained in `tests/README.md`.