When the source is parsed, and have been processed it is time to render the output. We will consider the following source snippet:
import Markdown
Markdown.parse("```julia\n" * rstrip(read("outputformats.jl", String)) * "\n```")
and see how this is rendered in each of the output formats.
Markdown output is generated by Literate.markdown. The (default) markdown output
of the source snippet above is as follows:
import Markdown
file = joinpath(@__DIR__, "../src/generated/name.md")
str = "````markdown\n" * rstrip(read(file, String)) * "\n````"
rm(file)
Markdown.parse(str)
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.
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 (png or jpeg) Literate will include the image representation of the output.
!!! note
Since Documenter executes and captures results of @example block it is not necessary
to use execute=true for markdown output that is meant to be used as input to
Documenter.
!!! compat "Literate 2.3" Code execution of markdown output requires at least Literate version 2.3.
See the section about Configuration for more information about how to configure the
behavior and resulting output of Literate.markdown.
Literate.markdown
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
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)Script output is generated by Literate.script. The (default) script output of the
source snippet above is as follows:
import Markdown
file = joinpath(@__DIR__, "../src/generated/outputformats.jl")
str = "```julia\n" * rstrip(read(file, String)) * "\n```"
rm(file)
Markdown.parse(str)
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
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.
!!! note "Configuration precedence"
Individual keyword arguments takes precedence over the config dictionary, so for e.g.
Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the
resulting configuration for name will be "world". Both individual keyword arguments
and the config dictionary takes precedence over the default.
Available configurations with description and default values are given in the reference for
Literate.DEFAULT_CONFIGURATION just below.
Literate.DEFAULT_CONFIGURATION