Package: pandoc-run-filter
pandoc-run-filterA simple pandoc filter that runs an embedded command or script in a markdown document capturing its output as an image or text.This tool has two basic use cases:Execute a program or command as specified in the markdownExecute a script that you embed in the markdown itselfThe tool then captures the output and passes it topandocas either:TextImageSo what could go wrong?/\  /\ !!!!!!!!! /\  /\
|! ||! |!!!!!!!!!|! ||! |
|! ||! |         |! ||! |
|! ||! | Warning |! ||! |
|! ||! |         |! ||! |
|__||__|!!!!!!!!!|__||__|
(__)(__)!!!!!!!!!(__)(__)Warning: Only run this tool on markdown content that you trust. Don't blindly run it on unverified content since inputs are executed while running pandoc./\  /\ !!!!!!!!! /\  /\
|! ||! |!!!!!!!!!|! ||! |
|! ||! |         |! ||! |
|! ||! | Warning |! ||! |
|! ||! |         |! ||! |
|__||__|!!!!!!!!!|__||__|
(__)(__)!!!!!!!!!(__)(__)Install$pipinstallpandoc-run-filterTest$pipinstallpytestpyfiglet
$pytest./tests/tests.pyRun$pandoc--filterpandoc-run-filtermyfile.md-omyfile.epubUninstall$pipuninstallpandoc-run-filter-yMarkdown Optionspandoc-run-filter looks for the following syntax in a markdown file where.runis the keyword.```{.run cmd="?" in="?" out="?" img="?"}
?
```Some examples ofcmdmight include:echopythondirlsmyprogram/home/user/myprogram../../myprogram...Next, theinparameter tells us howcmdshould be executed. We have two options here:Run as a shell command:in="shell"Run as an embedded script:in="script"Next, theoutparameter tells us how the output should be handled. We have a few options here too:Capture as text:out="text"Capture as an image:out="image"Ifoutis an image and what gets executed generates an image file, then we can use the optionalimgparameter to point to the path of that file. If this option is not provided, then this tool does its best to convert the output to an image.out="image"img="<path>"That's about it. Now, it's time for some examples. There were taken from the use cases under the./testsdirectory.Examples01.mdRun the echo command in a shell and capture the output as textMarkdown:```{.run cmd="echo" in="shell" out="text"}
'This is output as text.'
```Pandoc:pandoc-i01.md--filterpandoc-run-filter-o01.epubOutput:'This is output as text.'01.epub02.mdRun the echo command in a shell and convert the output to an imageMarkdown:```{.run cmd="echo" in="shell" out="image"}
'This is the output but converted to an image.'
```Pandoc:pandoc-i02.md--filterpandoc-run-filter-o02.epubOutput:02.epub03.mdRun an embedded python script and capture the output as textMarkdown:```{.run cmd="python" in="script" out="text"}
import pyfiglet
r = pyfiglet.figlet_format('Hi There!', font = 'banner')
print(f'''The is an embedded python script that generates ascii art.\n''')
print(r)
```Pandoc:pandoc-i03.md--filterpandoc-run-filter-o03.epubOutput:Theisanembeddedpythonscriptthatgeneratesasciiart.#     #      #######                             ####     # #       #    #    # ###### #####  ###### ####     # #       #    #    # #      #    # #      ########## #       #    ###### #####  #    # #####   ##     # #       #    #    # #      #####  ##     # #       #    #    # #      #   #  #      ####     # #       #    #    # ###### #    # ###### ###03.epub04.mdRun embedded python script and capture the output as a path to an image it createdMarkdown:```{.run cmd="python" in="script" out="image" img="04.png"}
from PIL import Image, ImageDraw, ImageFont
T = 'Hi There!'
W = 400
H = 400
shape = [(50, 50), (W - 10, H - 10)]
fnt = ImageFont.truetype('arial.ttf', 18)
image = Image.new(mode = 'RGB', size = (W, H), color='white')
draw = ImageDraw.Draw(image)
w, h = draw.textsize(T, fnt)
draw.rectangle(shape, fill ='#AAAAAA', outline ='#000000')
draw.text(((W-w)/2,(H-h)/2), T, font=fnt, fill='black')
image.save('04.png')
```Pandoc:pandoc-i04.md--filterpandoc-run-filter-o04.epubOutput:04.epubTroubleshooting TipsErrors being generated from embedded scripts:If you are seeing errors for embedded scripts, make sure that your script works as a standalone before inserting into the markdown.Runningpandoc-run-filterby itself without pandoc hangs:It's normal since it's expecting input from pandoc.Runningpandoc-run-filterkeeps throwing exceptions:Make sure that your markdown syntax is correct.Also run the tests to see if your environment is correct (see instructions above).Another pandoc filter is also using therunkeyword. What to do?Although not recommended, you can modify the variableMARKDOWN_TAG_NAME = 'run'inpandoc_run_filter.pyto something different and unique.Note:We are considering adding a new feature to support a configuration file or environment variables in the future where this can be changed without script modification.