literate-markdown.txt (9650B)
1 *literate-markdown.txt* A plugin for literate programming in Markdown. 2 3 Author: Alexander Balgavy <https://alex.balgavy.eu/> 4 License: Same terms as Vim itself (see |license|) 5 6 INTRODUCTION *literate-markdown* 7 8 Literate programming is the interleaving of code with explanation in natural 9 language, in any order, with the ability of generating just the executable 10 code from the file. People often know it from Org mode in Emacs; this plugin 11 aims to bring similar (but not identical!) functionality to Markdown files in 12 Vim. It will let you execute blocks of code (delimited by three backticks in 13 Markdown) and extract these blocks of code into separate files through 14 tangling. With macros, you can document your code without needing to care 15 about the order in which information is presented -- the tangler will extract 16 code in the correct order. 17 18 19 COMMANDS *literate-markdown-commands* 20 21 This plugin introduces a |ftplugin| file for the Markdown filetype, loaded 22 after the default files, which adds two commands: 23 24 :Tangle Extract code blocks according to 25 |literate-markdown-tangle| directives 26 :ExecPrevBlock Execute the previous code block (see 27 |literate-markdown-exec|) 28 29 MAPS *literate-markdown-maps* 30 31 This plugin introduces a |ftplugin| file for the Markdown filetype, loaded 32 after the default files, which adds two normal mode |<Plug>| mappings: 33 34 <Plug>LitMdTangle Extract code blocks according to 35 |literate-markdown-tangle| directives 36 <Plug>LitMdExecPrevBlock Execute the previous code block (see 37 |literate-markdown-exec|) 38 39 These mappings can be mapped to in e.g. after/ftplugin/markdown.vim in your 40 .vim directory (see |after-directory|): > 41 42 nmap <buffer> <leader>ce <Plug>LitMdExecPrevBlock 43 nmap <buffer> <leader>ct <Plug>LitMdTangle 44 < 45 46 CODE TANGLING *<Plug>LitMdTangle* *:Tangle* *literate-markdown-tangle* 47 Tangling is the extraction of source code from the Markdown file into separate 48 code files. 49 50 Code tangling is done using the |:Tangle| command, or using the mapping. It 51 proceeds according to directives, specified in the Markdown file itself, as 52 comments. 53 54 A directive takes the general form: > 55 <!-- :Tangle(language) /path/to/output/file.ext --> 56 < 57 58 The language is optional; you can use a generic directive: > 59 <!-- :Tangle /path/to/output/file.ext --> 60 < 61 62 If the language is specified, only blocks whose language matches the specified 63 language will be tangled to the file. If it is not specified, all code blocks 64 with a language will be tangled to the file. A tangle directive for a language 65 overrides all previous directives for that language for the remainder of the 66 file. A directive with no language specified overrides all previous directives 67 for the remainder of the file. 68 69 You can use macros. A macro is limited to the specified file and language, it 70 is not accessible from other files/languages. To specify that macros should be 71 expanded within a block, put "<>" in the block's tangle directive: > 72 <!-- :Tangle(language) <> /path/to/output/file.ext --> 73 < 74 75 76 Any files that use macros should have a top-level block (i.e. one that is not 77 contained in any other macro); this block should have "<^>" in its tangle 78 directive: > 79 <!-- :Tangle(language) <^> /path/to/output/file.ext --> 80 < 81 82 A macro in a code block has to be on its own line (preceded only by 83 whitespace), and is written in double angle brackets: > 84 <<this is a macro>> 85 < 86 87 A code block that defines the macro includes this macro in its tangle 88 directive, in single angle brackets: > 89 <!-- :Tangle(language) <this is a macro> /path/to/output/file.ext --> 90 < 91 92 The closing angle bracket in the macro name can optionally be followed by a 93 plus sign, which appends the contents of the block the the existing definition 94 of the macro: > 95 <!-- :Tangle(language) <this is a macro>+ /path/to/output/file.ext --> 96 < 97 The full format of a tangle directive, with optional parts in brackets, is: > 98 99 <!-- :Tangle[(language)] [<^>|<>] [<macro name>[+]] [/path/to/output/file.ext] --> 100 < 101 Please see the examples below, and the examples directory in the root of this 102 repository, for more explanation of usage. 103 104 Examples~ 105 106 Below are some examples of Markdown code block tangling, followed by 107 explanations. 108 109 > 110 <!-- :Tangle(ruby) /tmp/output.rb --> 111 112 ```ruby 113 puts "Sample text" 114 ``` 115 116 ```bash 117 echo "Sample text" 118 ``` 119 120 <!-- :Tangle(ruby) /tmp/another.rb --> 121 ```ruby 122 puts "Another file" 123 ``` 124 < 125 126 The first Ruby code block is affected by the first tangle directive, so it 127 will be tangled to /tmp/output.rb. There is no generic directive, so the Bash 128 code block will not be tangled. The second tangle directive for Ruby overrides 129 the first, so the second Ruby code block will be tangled to /tmp/another.rb 130 (and so would any subsequent Ruby code blocks). 131 132 > 133 <!-- :Tangle /tmp/generic-file --> 134 <!-- :Tangle(python) /tmp/python.py --> 135 136 ```ruby 137 puts "Sample text" 138 ``` 139 140 ```python 141 print("Sample text") 142 ``` 143 144 ``` 145 this is some pseudocode in a block with no language 146 ``` 147 148 ```bash 149 echo "Sample text" 150 ``` 151 < 152 153 The first Ruby code block is affected by the first (generic) tangle directive, 154 so it will be tangled to /tmp/generic-file. The Python code block is affected 155 by the second Python-specific directive, so it will be tangled to 156 /tmp/python.py. The third code block does not have a language specified, so it 157 will not be tangled. The fourth (Bash) code block is affected by the first 158 (generic) tangle directive, so it will be tangled to /tmp/generic-file. 159 160 161 > 162 <!-- :Tangle(python) <^> /tmp/python.py --> 163 ```python 164 <<function definitions>> 165 166 def main(): 167 <<main code>> 168 169 if __name__ == '__main__': 170 main() 171 ``` 172 173 <!-- :Tangle(python) <function definitions> --> 174 ```python 175 def double(n): 176 x = 2*n 177 return x 178 ``` 179 180 <!-- :Tangle(python) <> <main code> --> 181 ```python 182 <<n definition>> 183 print("Double of %d is %d" % (n, double(n))) 184 ``` 185 186 <!-- :Tangle(python) <n definition> --> 187 ```python 188 n = 34.5 189 ``` 190 < 191 192 The first Python block defines the overall structure, so it's the top level 193 macro block (indicated by "<^>" in its tangle directive). It makes use of two 194 macros, "function definitions" and "main code". The second block defines the 195 "function definitions" macro; it does not contain any more macros, so it does 196 not have "<>" in its tangle directive. The third block defines the "main code" 197 macro, and contains another macro to be expanded ("n definition"), so it has 198 "<>" in its tangle directive. The final block defines the "n definition" macro 199 and does not contain any other macros. The resulting code will be > 200 def double(n): 201 x = 2*n 202 return x 203 204 def main(): 205 n = 34.5 206 print("Double of %d is %d" % (n, double(n))) 207 208 if __name__ == '__main__': 209 main() 210 < 211 212 213 214 CODE EXECUTION *:ExecPrevBlock* *literate-markdown-exec* 215 *<Plug>LitMdExecPrevBlock* 216 217 This plugin allows stateless code execution. The standard output from the 218 block will be printed in the current buffer. State is NOT preserved between 219 code blocks. 220 221 The command |:ExecPrevBlock| or the mapping |<Plug>LitMdExecPrevBlock| look 222 for the most recent code block with a specified language, which is either the 223 block containing the cursor, or the first code block encountered when 224 searching backwards from the cursor. 225 226 The block is executed using a command looked up using a predefined dictionary, 227 mapping a command to a |list| of Markdown block language names. It can be 228 extended by adding entries to b:literate_markdown_interpreters or 229 g:literate_markdown_interpreters, which are looked up in that order (with a 230 fallback to the predefined dictionary). 231 232 The defaults are: > 233 234 { 'python3': ['py', 'python', 'python3'], 235 \ 'python2': ['python2'], 236 \ 'ruby': ['rb', 'ruby'], 237 \ 'sh': ['sh'], 238 \ 'bash': ['bash'] 239 \ } 240 < 241 242 This means that in the code blocks > 243 244 ```python 245 print("Sample text") 246 ``` 247 248 ```sh 249 echo "Sample text" 250 ``` 251 < 252 253 the first block will be executed with the python3 command, and the second code 254 block will be executed with the sh command. 255 256 Blocks are executed by sending them on standard input to the command. The 257 command resolves to its path in your shell environment. 258 259 The output will be shown beneath the code block, in the form: > 260 261 <!-- 262 RESULT: 263 {output} 264 --> 265 < 266 {output} will be replaced with the output of the block. 267 268 CONFIGURATION *literate-markdown-config* 269 270 You can specify commands for languages via b:literate_markdown_interpreters or 271 g:literate_markdown_interpreters, as explained in |literate-markdown-exec|. 272 273 You can skip loading the plugin by setting g:loaded_literate_markdown, and you 274 can skip loading autoload functions by setting 275 g:loaded_literate_markdown_autoload. 276 277 You can remap the <Plug> mappings as explained in |literate-markdown-maps|. 278 279 To disable automatically opening tangled files, set 280 g:literate_markdown_no_open_tangled_files. 281 282 To echo some debug information, set g:literate_markdown_debug. 283 284 DISCLAIMER 285 286 This plugin has not been tested on Windows, so the behavior of some functions 287 (e.g. code block execution) may be different or may not work properly. 288 289 ABOUT *literate-markdown-about* 290 291 Get the latest version or report a bug on GitHub: 292 293 https://github.com/thezeroalpha/vim-literate-markdown 294 295 vim:tw=78:et:ft=help:norl: