4. Output formats

When the source is parsed, and has been processed it is time to render the output. We will consider the following source snippet:

# # Rational numbers
#
# In julia rational numbers can be constructed with the `//` operator.
# Lets define two rational numbers, `x` and `y`:

x = 1 // 3
#-
y = 2 // 5

# When adding `x` and `y` together we obtain a new rational number:

z = x + y

and see how this is rendered in each of the output formats.

4.1. Markdown output

Markdown output is generated by Literate.markdown. There exist various "flavors" of markdown and Literate supports some different flavors, see Markdown flavors. The default flavor is Literate.DocumenterFlavor() and, as the name suggest, it generates markdown files meant to be used together with Documenter.jl. The output of the source snippet above is as follows:

```@meta
EditURL = "../outputformats.jl"
```

# Rational numbers

In julia rational numbers can be constructed with the `//` operator.
Lets define two rational numbers, `x` and `y`:

````@example name
x = 1 // 3
````

````@example name
y = 2 // 5
````

When adding `x` and `y` together we obtain a new rational number:

````@example name
z = x + y
````

We note that lines starting with # are printed as regular markdown, and the code lines have been wrapped in @example blocks. We also note that an @meta block have been added, that sets the EditURL variable. This is used by Documenter to redirect the "Edit on GitHub" link for the page, see Interaction with Documenter.

The @example blocks are wrapped in 4 consecutive backticks so as to allow for docstrings containing triple backticks, for example:

"""
This function perform the following calculation:
```math
    x_1 + x_2
```
"""
f(x) = x[1] + x[2]

If your Julia code itself contains 4 consecutive backticks, you can use the keyword argument codefence to setup 5 backticks for code blocks, see Configuration.

It possible to configure Literate.markdown to also evaluate code snippets, capture the result and include it in the output, by passing execute=true as a keyword argument. The result of the first code-block in the example above would then become

````julia
x = 1//3
````
````
1//3
````

In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (image/png or image/jpeg), HTML (text/html) or markdown (text/markdown) Literate will include the richest representation of the output.

See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.

Literate.markdown(inputfile, outputdir=pwd(); config::AbstractDict=Dict(), kwargs...)

Markdown flavors

Literate can output markdown in different flavors. The flavor is specified using the flavor keyword argument. The following flavors are currently supported:

• flavor = Literate.DocumenterFlavor(): this is the default flavor and the output is meant to be used as input to Documenter.jl.
• flavor = Literate.CommonMarkFlavor(): this outputs markdown that has the flavor of the CommonMark specification.
• flavor = Literate.FranklinFlavor(): this outputs markdown meant to be used as input to Franklin.jl.
• flavor = Literate.QuartoFlavor(): this outputs markdown file (with file extension .qmd) meant to be used with Quarto CLI.

Quarto flavor

Quarto is an open-source scientific and technical publishing system, which can extend the range of output formats from your Literate.jl-formatted scripts. Literate.jl will produce a .qmd file, which can be used as input to Quarto CLI to produce a variety of output formats, including HTML, PDF, Word and RevealJS slides.

Literate + Quarto syntax tips

• #(hashtag followed by a space) at the beginning of a line will be stripped and anything that follows will rendered as a markdown, e.g., # # Header level 1 in your script will be rendered as # Header level 1 in your .qmd file (ie, it will show as a header). Use this for adding the YAML header at the top or any Markdown blocks in the Quarto guide.
• ##|(two hashtags followed by a pipe) at the beginning of a line will strip the first hashtag and interpret the remainder of the line as part of the code block. This is useful to provide Quarto commands in computation blocks, e.g., ##! echo: false would be rendered as #| echo: false and would tell Quarto not to "echo" the outputs of the execution (see Guide: Executions options for more commands).
• Make sure to always provide the YAML header and specify IJulia kernel when executing the file by Quarto, e.g.,

  # ---
  # title: "My Report"
  # jupyter: julia-1.9
  # ---

  Notice how all lines are escaped with a # so Literate.jl knows to strip the hashtags and render it as markdown (see Authoring Tutorial for more examples)
• If any markdown components (e.g. headers) are not rendering correctly in your Quarto outputs, make sure they are surrounded by empty lines (e.g., add an empty line before and after the header) to help Quarto parse them correctly

Configuring Quarto for Julia code execution

• Install Quarto CLI
• Run quarto check to ensure all is installed correctly (you will need Python, Jupyter, and IJulia kernel, see Getting Started)

Steps to create reports

• Make sure you have the right header specifying which IJulia kernel to use (e.g. jupyter: julia-1.9), otherwise Quarto will use the default Python kernel.
• Convert your Literate.jl script to a .qmd file, e.g.

  Literate.markdown("my_script.jl", flavor = Literate.QuartoFlavor())

• Run Quarto CLI to produce your desired output format, e.g.

  quarto render my_script.qmd --to html

4.2. Notebook output

Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.

We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.

See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.

Literate.notebook(inputfile, outputdir=pwd(); config::AbstractDict=Dict(), kwargs...)

Notebook metadata

Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows

%% optional ignored text [type] {optional metadata JSON}

Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.

The following would create a 3 slide deck with RISE:

#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
# # Some title
#
# We're using `#nb` so the metadata is only included in notebook output

#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
x = 1//3
y = 2//5

#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
# For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)

4.3. Script output

Script output is generated by Literate.script. The (default) script output of the source snippet above is as follows:

x = 1 // 3

y = 2 // 5

z = x + y

We note that lines starting with # are removed and only the code lines have been kept.

See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

Literate.script(inputfile, outputdir=pwd(); config::AbstractDict=Dict(), kwargs...)

4.4. Configuration

The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

DEFAULT_CONFIGURATION