Markdown usage

Asciicast provides facilities for maintaining gifs showcasing package functionality in READMEs, or otherwise adding animated gifs to Julia code blocks in documents.

julia {cast="true"} code blocks

To use functionality, simply add julia {cast="true"} code-blocks to your document. For example,

```julia {cast="true"}
using Pkg
Pkg.status()
```

Then run cast_document (or the helper cast_readme) on the file. This will turn it into:

```julia {cast="true"}
using Pkg
Pkg.status()
```
![](assets/output_1_@cast.gif)

and generate a gif in the assets directory.

One can also customize the font-size and the delay:

```julia {cast="true" font-size=28 delay=0.5}
using Pkg
Pkg.status()
```

Note that the attributes must be separated by spaces, not commas, as shown above.

Here, the gifs are generated with agg (which is installed automatically using a JLL package), and the font-size parameter is passed there. Currently no other agg parameters are supported, but file an issue if you have a use for one.

Named blocks

One can name blocks to continue execution after interrupting by some text. For example:

Here we have `x`:
```julia {cast="true" name="ex1"}
x=2

```

Now we add 1:
```julia {cast="true" name="ex1"}
y = x+1

```

This works the same way as named example blocks in Documenter.

All supported attributes

• delay::Float64=0.25. The amount of delay between line executions (to emulate typing time).
• font-size::Int=28. Used by agg when generating the gif.
• height::Int. Heuristically determined by default. Set to an integer to specify the number of lines.
• allow_errors::Bool=false. Whether or not cast_document (or cast_readme) should fail if exceptions are encountered during execution of the block.
• name::String. Optionally provide a name to allow running multiple examples in the same module, similar to named example blocks in Documenter.

Syntax notes

A note on the syntax. Here we want to ensure that the code snippet continues to get syntax highlighting, but also mark it somehow so we can detect that we want to generate a gif for this snippet. The implementation behind-the-scenes uses pandoc, so we are somewhat limited by what pandoc can support. Here, we are using "attributes" ({cast="true"}) so we can keep "julia" as the first "class", so that syntax highlighting still works, while being able to pass cast="true" into the pandoc AST so that we can detect it there and generate the gif. I initially tried just julia-cast or julia:@cast as the language, but GitHub stops providing julia highlighting in that case.

Additionally, I use @cast in the output filename, so that future runs can identify @cast-generated gifs and remove the image tags, to prevent duplicating them when running cast_document again to update the gifs.

Reference docs

cast_readme(MyPackage::Module)
cast_readme(MyPackage::Module, output_path)

cast_document(input_path, output_path=input_path; format="gfm+attributes")