Support for silent blocks
Opened this issue · 8 comments
It would be nice to have support for blocks that evaluate, but do not produce any markdown output.
I'm writing some tutorial for a library in mdx, and need to have a snippet of code of 20-30 lines to present to the reader. Writing it in toplevel block directly is not very convenient as it won't get automatically formatted. Making it a file block solves the problem of formatting, but the code is not evaluated in mdx context. My best approach so far it to load it into toplevel via #use directive, but it outputs a lot of signatures along the way. Once loaded, I can present separate sections of the file via file blocks and then show some toplevel evaluation of the constructs defined in the file. With silent block I could load it without extra noise in the markdown output.
I am a bit confused, given the idea of MDX is to essentially present a fixed point of evaluation (modulo non-deterministic blocks), in that case not rendering the block would make it disappear from the next run. That's also why MDX files can be promoted using dune, so documents using silent blocks would silently promote into documents missing these blocks altogether.
Also, if it doesn't produce any output, how would error reporting work, if the block never renders anything? So whether it is correct or not would not yield any feedback to the documentation writer.
Silent block changes the environment and if consecutive blocks depend on it, diff & promotion workflow will work as expected. So far I worked around this via summary/details markdown tags (see this gist) to collapse the output of #require and #use at the beginning of my markdown file and hide this from the reader.
How will it work? If the block is silent, it will be missing in the output, thus promotion will promote a version that doesn't feature it, thus breaking the document.
I currently have the following block at the start of my mdx (using 2 backticks to not mess the outer markdown):
``ocaml
# #require "ppx_yojson_conv";;
# #require "my-lib";;
# #use "test/Mdx_parts.ml";;
``
It does produce some output, as Mdx_parts.ml has some modules and functions defined, but I want to hide inferred signatures from the reader at this point.
Later on in my document I expand on some subject, and output a relevant piece of Mdx_parts.ml like this:
<!-- $MDX file=test/Mdx_parts.ml,part=myCodePart -->
``ocaml
``
This shows a piece of code to the reader, and after I presented this code, I want to show how one can use it with toplevel blocks.
Probably I could just move that Mdx_parts.ml into a separate library that I can #require from toplevel block, this will avoid printing of module signatures when I don't want that. Library with example code for mdx sounds a bit counterintuitive at first though.
Both Rmarkdown [1] and IPython [2] do support supressing block output, so probably this feature is considered useful for side effects of some computation.
[1] https://bookdown.org/yihui/rmarkdown-cookbook/hide-all.html
[2] https://ipython.org/ipython-doc/3/interactive/tips.html#suppress-output
Mdx already supports this kind of block, simply remove the prefixes #:
``ocaml
(* Comment to prevent Mdx from interpreting the '#'. *)
#require "ppx_yojson_conv";;
#require "my-lib";;
#use "test/Mdx_parts.ml";;
``@Julow but I want the block to be actually executed, just the output to not be emitted in the document.
It is:
```ocaml
let x = 42
```
```ocaml
# x ;;
- : int = 42
```
Oh, nice! Probably it's worth mentioning in the documentation explicitly that one can add a silent block that still evaluates.