gpanders/vim-medieval

Evaluate Markdown code blocks within Vim

vim-medieval

Evaluate Markdown code blocks within Vim.

Description

Medieval allows you to evaluate code blocks in Markdown buffers of the following form:

```bash
echo "Hello world!"
```

By placing your cursor anywhere in the code block above and running :EvalBlock, Medieval will print the result of evaluating the block (in this case, it will echo "Hello world!")

You can send the output of evaluation into another code block, allowing you to do a primitive style of literate programming. You can accomplish this by adding a "target" parameter to your code block and creating a second code block with a "name" parameter. The output of the evaluation of your code block will be redirected to the targeted block. For example:

<!-- target: squares -->
```python
print([x*x for x in range(5)])
```

<!-- name: squares -->
```
```

If you run :EvalBlock in the first code block, the second block will become

<!-- name: squares -->
```
[0, 1, 4, 9, 16]
```

Medieval can do a lot more. Read :h medieval for the full documentation.

Create a mapping

Medieval does not create any mappings by default, but you can easily create one yourself by adding the following to the file ~/.vim/after/ftplugin/markdown.vim (create it if it does not yet exist):

nmap <buffer> Z! <Plug>(medieval-eval)

Limitations

For now, Medieval only works in Markdown buffers. If you'd like to see support added for other file types, please see the Contributing section.

Contributing

Please feel free to contribute changes or bug fixes. You can send patches to [email protected] or submit a pull request on GitHub.

vim-medieval's Issues

Feature request: create result code block if "target" does not match any "name"

Hi again! And thank you for the implementation of the dependent blocks!

I have a suggestion to save some time writing while using the plugin. Now, when you have something like

<!-- target: output -->
```sh
echo "hi"
```

and nothing else, and you run :EvalBlock, you get the message medieval: Couldn't find block "output" and nothing happens. But a code block with a target will always need an output cell with the specified name, so why not create it automatically if it does not find any?

Suggested behavior:

• Initial code block:

<!-- target: output -->
```sh
echo "hi"
```

• Run :EvalBlock. If there is no matching "output" cell, create it with the execution results inside:

<!-- target: output -->
```sh
echo "hi"
```

<!-- name: output -->
```
hi
```

[Feature request] Add a hook or event at end of evaluation

I use a rather hacky trick to change the background color of code blocks by use of signs. I would like to refresh the signs to get the colors correct after doing :EvalBlock, but I find it hard to do in a good manner. It seems :EvalBlock runs in a background job and updates the target output when the job is complete. Thus, doing things like this won't work:

nmap <buffer> <leader>ar <plug>(medieval-eval)<cmd>:call UpdateMySigns()<cr>

I was hoping you could add either an event like EvalBlockComplete, or, perhaps better, a new entry to the medieval#eval option dictionary, e.g. after:

function! s:after(ctx, input)
  echo "EvalBlock is finished and file is updated."
endfunction

call medieval#eval('', #{after: function('s:after')})

Perhaps a help text like this:

		  after:	(function) A function to be called when
				evaluation completes, after the output is
				written to the target block. The function
				accepts two arguments: a "context" |Dict|
				containing the parameters used to evaluate the
				block and the result of the block evaluation
				as a list of lines.

I'm not sure if the context and output line arguments are necessary in this case, but I guess they won't hurt and allows further flexibility to the user?

Feature request: Asynchronous execution

Would it be possible to support asynchronous execution of code blocks in Neovim and Vim. So you could type something like

```python :async

to make the execution async.

Feature request: Run code blocks above

I'm interested in literate programming, so it would be nice if one could run code written in different in several code blocks, since it can lead to a cleaner file. For example, one could define some libraries in a code block with a defined id: library, and then tell the next code block to run first the block with id: library. An example in python would be:

<!-- id: library -->
```python
import numpy as np
```  
Some explanation of `numpy` library here. Now example of usage:

<!-- target: array, run-before: library -->
```python
print(np.array([1,2,3])
```

<!-- name: array -->
```
result
```

Would it be easy to implement?

Last line missing from output when it doesn't have an endline

Given this code block:

<!-- target: out -->
```sh
curl -s https://jsonplaceholder.typicode.com/todos/1
```

I get the following output from doing :EvalBlock:

<!-- name: out -->
```json
{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
```

I believe the problem is related to the fact that the curl output does not have a final endline?

(By the way, thanks for this plugin. I find it quite convenient for e.g. simple testing of shell commands and curl calls!)

`:EvalBlock` not working

Hi. As I mentioned in the feature-request, :EvalBlock is not working for me.

My configuration:

Plug 'gpanders/vim-medieval', { 'branch': 'master' }
let g:medieval_langs = ['python', 'sh', 'console=bash']

Minimal Example:

<!-- target: output -->
```python
print("hi")
```

<!-- name: output -->
```
```

• Running :EvalBlock does nothing.
• Running :EvalBlock! results, as expected, in

<!-- target: output -->
```python
hi
```

<!-- name: output -->
```
```

• Running :EvalBlock output results, as expected, in

<!-- target: output -->
```python
print("hi")
```

<!-- name: output -->
```
hi
```

I don't know how to debug this to pin down the problem, but if you tell me I can try stuff.

Regex Custom Block Support

I've started using the static website generator Hugo which uses Go templates for user defined shortcodes.

With this use case in mind, it would be great if there was another variable where users could specify regex to select any type of block they wanted.

In .vimrc:

" Opening/Closing pair (in case that's needed)
let g:medieval_output_blocks = [
    ["```", "```"],
    ["$$", "$$"],
    ["{{<\s[\S]*\s>}}", "{{<\s\/[\S]*\s>}}"]
]

This would allow me to use it like this:

<!-- target: math -->
```python
print(r"\text{Hello KaTeX!}")
```

<!-- name: math -->
{{< katex >}}
\text{Hello KaTeX!}
{{< /katex >}}

[Question] Feature comparison with org-babel.

I was on the lookout for tools to replace the various functionalities of Emacs' org-mode. An important piece of org-mode is
org-babel which is for literate programming. In case you are familiar with org-babel, how close do you feel vim-medieval is,
to having feature parity with it? Example of a nifty thing org-babel does: there's this option to tangle a code-block(or blocks in
a single language) into a separate source file for that language, this is handy in certain situations, the code block can then be edited in a separate buffer with all the LSP(and other) functionality associated with that filetype, once you are done editing the changes could be saved across both the copies (the tangled source-file and the original org-document).