Literate.jl

Literate is a package designed for Literate Programming. It allows you to write a single commented Julia script as your source of truth and automatically generates multiple output formats from it. This ensures that your documentation, interactive notebooks, and executable scripts stay in sync with minimal maintenance.

By using a single source file, you can provide users with different ways to consume your package's examples: markdown for reading, notebooks for interactive exploration, and plain scripts for direct execution.

The functions Literate.markdown, Literate.notebook, and Literate.script can be configured using keyword arguments or a config::Dict object.

Precedence Rules:

1. Individual keyword arguments (highest priority).
2. The config dictionary.
3. Literate.DEFAULT_CONFIGURATION (lowest priority).

Example of precedence: Literate.markdown(..., config = Dict("name" => "hello"), name = "world") will result in the name being "world".

You can inject Jupyter metadata (for tools like nbgrader or RISE) into cells using the %% token. The syntax is:

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

To ensure metadata is only included in the notebook output and not in other formats, prefix the line with #nb:

#nb %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
# # Some title

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

The behavior of the Document generation step depends on the chosen output format:

Literate source files are standard Julia (.jl) scripts. This design allows scripts to serve as both documentation and executable code that can be included in test suites (e.g., via include) to ensure examples remain up to date.

Basic Syntax Rules:

• Lines starting with # (hash followed by a space) are treated as Markdown.
• All other lines are treated as Julia code.
• Leading whitespace before # is allowed but is removed during output generation.
• To use regular Julia comments that render as # in the output, use ## (double hash).

## This renders as a Julia comment in output
# This is a Markdown heading
#
# This is a Markdown paragraph.

x = 1 // 2

By default, Literate groups adjacent lines of the same type into chunks. To manually force a split between chunks (for example, to separate code into different notebook cells or @example blocks), use chunk-splitter tokens at the start of a line:

• #-: Forces a split. The rest of the line is discarded. You can use decorative versions like #------------- for readability.
• #+: Forces a split and enables Documenter.jl "continued"-blocks.

Example of forcing a split in a Julia code block:

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

Since admonitions are not natively supported in Jupyter notebooks, you can use a preprocess function in Literate.markdown or Literate.notebook to transform a custom syntax into different formats.

For example, you can use a custom tag like #note # and write a preprocessor that converts it into a standard !!! note admonition for Markdown files, and a blockquote (> *Note*) for Notebook files.

function md_note(str)
    str = replace(str, r"^#note # (.*)$"m => s"""
    # !!! note
    #     \1""")
    return str
end

function nb_note(str)
    str = replace(str, r"^#note # (.*)$"m => s"""
    # > *Note*
    # > \1""")
    return str
end

using Literate

# For Markdown
Literate.markdown("example.jl", "tmp/"; preprocess = md_note)

# For Notebooks
Literate.notebook("example.jl", "tmp/"; preprocess = nb_note)

Literate supports two ways to write large blocks of Markdown without prefixing every line with # :

1. Julia Multiline Comments

Use standard Julia multiline comments (#= ... =#). The start and end tokens must be on their own lines. Literate rewrites these to regular # comments during preprocessing.

2. Literal Markdown Strings

You can use md""" ... """ to define markdown blocks. Note: This feature is not enabled by default. You must pass mdstrings=true to Literate.markdown, Literate.notebook, or Literate.script to use it.

#= 
This multiline comment
is treated as markdown.
=#

# Enabling md""" strings:
Literate.markdown(io, "file.jl"; mdstrings=true)

md"""
# Title
blah blah blah
"""

The final step of the pipeline writes the generated file to a specific location:

• Path structure: $(outputdir)/$(name)(.md|.ipynb|.jl)
• outputdir: The directory supplied by the user (e.g., docs/generated).
• name: The filename supplied by the user.

Best Practice: Add your outputdir to .gitignore, as these files are intended to be generated as part of the build process rather than being tracked in version control.

When using Literate to generate documentation for a Julia package, you can pass the keyword argument documenter = true to the generators (Literate.markdown, Literate.notebook, or Literate.script). This enables specific transformations that make your source files compatible with Documenter.jl features while ensuring the output files (Markdown, Notebooks, or Scripts) are correctly formatted for their respective environments.

# Example usage pattern
Literate.markdown(["src/example.jl"], "docs/src"; documenter = true)