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

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

```julia {cast="true"}
using Pkg

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

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"}


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, output_path)

Add gifs for each julia {cast="true"} code-block in the README of MyPackage. This is just a smaller helper that calls cast_document on joinpath(pkgdir(MyPackage), ""). See cast_document for more options and warnings.

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

For each julia {cast="true"} code-block in the input document, generates a gif executing that code in a REPL, saves it to joinpath(dirname(output_path), "assets") and inserts it as an image following the code-block, writing the resulting document to output_path.

The default format is Github-flavored markdown. Specify the format keyword argument to choose an alternate pandoc-supported format (see This has only been tested with Github-flavored markdown, but theoretically should work with any pandoc format.

Returns the number of gifs generated.


This function relies on parsing the document using pandoc and roundtripping through the pandoc AST. This can result in unexpected modifications to the document.

It is recommended to check your document into source control before running this function, or specifying an output_path that is different from the input path, in order to assess the results.