Literate.jl: one Julia file that becomes documentation, a notebook and a script

One source file, several outputs

Literate is a package for literate programming, and the main purpose is stated plainly: to facilitate writing Julia examples and tutorials that can be included in your package documentation.

The mechanism is that a single Julia source file becomes several artefacts. Literate can generate markdown pages, for example for Documenter.jl, and it can generate Jupyter notebooks, from the same source file. There is also an option to clean the source from all metadata and produce a pure Julia script.

The reason to care is stated in the README in one sentence: using a single source file for multiple purposes reduces maintenance and makes sure your different output formats are synced with each other.

That is the whole argument for the package, and it is a stronger argument than it first appears. A Julia package has a doc build, a test suite and a set of examples, and the traditional arrangement is that each of those is written separately and drifts. A literate source file, where the prose and the code live together, removes the possibility of a tutorial that no longer runs, because the tutorial and the code are the same text.

The topics attached to the repository name the territory: documentation, documentation-generator, documentation-tool, julia and literate-programming. It is a documentation tool first and a programming tool second, and the script output is a side effect of the same pipeline.

The licence field on the repository is recorded as a custom licence that GitHub cannot classify, with the actual text in LICENSE.md, and the package metadata lives in Project.toml with the sources under src/ and the tests under test/.

The project documents itself with itself

The detail that makes this repository worth reading is that the README of Literate is itself an artefact of Literate.

The README states that it was generated directly from a source file, examples/README.jl, by running two commands from the package root:

using Literate
Literate.markdown("examples/README.jl", "."; flavor = Literate.CommonMarkFlavor())

The page ends with the confirmation, that it was generated using Literate.jl, and the same notice appears in the footer of the rendered output. So the package is used on itself, and the repository doubles as a worked example of the workflow rather than a description of it.

Two details in that command are worth understanding. The first argument is the source file and the second is the output directory, so the generated markdown lands next to the package root. And the keyword argument flavor selects a markdown flavour, here Literate.CommonMarkFlavor(), which tells the generator which dialect to emit.

That flavour parameter is the part that matters in practice. Markdown is not one format, and a documentation toolchain that expects a particular dialect will choke on the wrong one, so being able to say which flavour you want is a real feature rather than a detail.

The examples/ directory holds the two source files the project ships, README.jl and example.jl, and the documentation site is published at fredrikekre.github.io/Literate.jl, with a badge for the latest release and the CI badge for the Test workflow on the master branch.

Weave and Quarto run the pipeline in the other direction

The related packages section names the two tools that do the neighbouring job, and the difference in approach between them and Literate is instructive.

Weave.jl can generate Jupyter notebooks, HTML or PDF directly from a Markdown format containing Julia code blocks. Quarto can do the same, and also works with R and Python. The README adds a note that Literate.jl can produce Quarto input markdown files, with the .qmd extension, as well.

So the pipelines run in opposite directions. Literate starts with a Julia source file that contains the prose and the code, and generates the markdown or the notebook from it. Weave and Quarto start with a Markdown file that contains Julia code blocks, and generate the notebook or the rendered output from it.

That difference decides which one fits a project. If your examples are already written as Markdown, Literate adds a conversion step and buys you little, and Weave or Quarto is the tool that was designed for your file. If your examples are written as Julia files that must also remain runnable as scripts, Literate is the one that fits, and its cleaning option is the reason, because it produces the pure Julia script from the same file.

The Quarto note is the interesting middle case. Producing .qmd input means a Literate workflow can hand off to a Quarto pipeline, so the two are not rivals so much as two stages, and the choice of which to start from is a project decision rather than a tooling decision.

What the outputs are and are not

The division of labour between the three outputs is what decides how much work Literate saves you.

The markdown output is the one that feeds a documentation build. The README names Documenter.jl as the example, and the flavour argument is the contract with whichever tool consumes it, so the generator is producing input for another tool rather than the final page. That is the important consequence: Literate does not replace your documentation tool, it feeds it.

The notebook output is a Jupyter notebook, which is a runnable artefact. Its usefulness depends on what executes it, and the documentation for Literate describes it as generating the notebook from the source file, with the related packages described as the ones that generate a notebook, HTML or PDF directly from a Markdown file containing Julia code blocks. The sensible reading is that the execution step belongs to whatever consumes the generated file, and the source of truth stays the literate source.

The clean script output is the odd one out and the most useful in a specific situation. Removing all the metadata and leaving a pure Julia script means the example can be run, tested and shipped as code, with the prose in the documentation and the behaviour in the repository, and nobody has to keep two copies in step.

For a package author, the combination is the point. The doc build gets markdown, a newcomer gets a notebook they can run, and your test suite gets a script it can execute, and all three come from one file that cannot disagree with itself.

Where Literate.jl is the wrong tool

Three limits are clear from the scope of the project.

The first is that it is Julia specific. The package reads a Julia source file and produces Julia examples, and there is nothing in the description suggesting a language agnostic version. A project that documents its examples in Python or R is served by Weave or by Quarto, and Quarto is explicitly noted as working with R and Python as well.

The second is the direction of the pipeline, which is the same point from the other side. If your source of truth is already a Markdown document, Literate is a converter you do not need, and it is a converter with a language constraint on top.

The third is the licence and the maintenance profile. The licence field is recorded as a custom licence that GitHub cannot classify, with LICENSE.md in the repository, and for a package that sits in the documentation path of other people that is the file to read. The project is not archived and the last push was on 2026-07-08, and the release history shows v2.21.0 on 2025-11-19, v2.20.1 on 2024-10-17 and v2.20.0 on 2024-10-16, so it is a small project with a steady patch cadence rather than a large one.

There is a fourth, smaller point about the ecosystem. The project is tied to the Julia documentation toolchain, and the code style badge points at the Runic.jl repository, which is a sign of a coherent little ecosystem rather than an isolated tool. The practical consequence is that if your organisation has standardised on a different markdown generator and a different formatter, Literate is a second convention rather than a first one.

Editorial conclusion

Adopt Literate.jl if you maintain a Julia package whose examples are written as literate source files and you want the same file to produce your Documenter pages, a runnable notebook and a clean script. Do not adopt it if your documentation pipeline is driven from Markdown already, since Weave.jl and Quarto fill that role, or if you are outside Julia, since the package is Julia specific. Verify first which markdown flavour your documentation tool expects, because the generator takes a flavour argument, and check that the cleaning option gives you a script whose metadata removal still leaves it runnable.

Frequently asked questions

Official sources

1. fredrikekre/Literate.jl on GitHub
2. Issues
3. Project website
4. README
5. Releases