Literate.jl/docs/src/fileformat.md

2. File Format

The source file format for Literate is a regular, commented, julia (.jl) scripts. The idea is that the scripts also serve as documentation on their own and it is also simple to include them in the test-suite, with e.g. include, to make sure the examples stay up do date with other changes in your package.

[2.1. Syntax](@id Syntax)

The basic syntax is simple:

• lines starting with #' is treated as markdown,
• all other lines are treated as julia code.

The reason for using #' instead of # is that we want to be able to use # as comments, just as in a regular script. Lets look at a simple example:

#' # 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

In the lines #' we can use regular markdown syntax, for example the # used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:

• The script is valid julia, which means that we can include it and the example will run (for example in the test/runtests.jl script, to include the example in the test suite).
• The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.

For simple use this is all you need to know. The following additional special syntax can also be used:

• #md, #nb, #jl: tags for filtering of lines, see [Filtering Lines](@ref Filtering-Lines).
• #-: tag for manually controlling chunk-splits, see Custom control over chunk splits.

There is also some default convenience replacements that will always be performed, see Default Replacements.

[2.2. Filtering Lines](@id Filtering-Lines)

It is possible to filter out lines depending on the output format. For this purpose, there are three different "tokens" that can be placed on the start of the line:

• #md: markdown output only,
• #nb: notebook output only,
• #jl: script output only.

Lines starting with one of these tokens are filtered out in the [preprocessing step](@ref Pre-processing).

Suppose, for example, that we want to include a docstring within a @docs block using Documenter. Obviously we don't want to include this in the notebook, since @docs is Documenter syntax that the notebook will not understand. This is a case where we can prepend #md to those lines:

#md #' ```@docs
#md #' Literate.markdown
#md #' Literate.notebook
#md #' Literate.markdown
#md #' ```

The lines in the example above would be filtered out in the preprocessing step, unless we are generating a markdown file. When generating a markdown file we would simple remove the leading #md from the lines. Beware that the space after the tag is also removed.

[2.3. Default Replacements](@id Default-Replacements)

The following convenience "macros" are always expanded:

• @__NAME__

  expands to the name keyword argument to Literate.markdown, Literate.notebook and Literate.script (defaults to the filename of the input file).

• @__REPO__ROOT_URL__

  expands to https://github.com/$(ENV["TRAVIS_REPO_SLUG"])/blob/master/ and is a convenient way to use when you want to link to files outside the doc-build directory. For example @__REPO__ROOT_URL__src/Literate.jl would link to the source of the Literate module.

• @__NBVIEWER_ROOT_URL__

  expands to https://nbviewer.jupyter.org/github/$(ENV["TRAVIS_REPO_SLUG"])/blob/gh-pages/$(folder)/ where folder is the folder that Documenter.deploydocs deploys too. This can be used if you want a link that opens the generated notebook in http://nbviewer.jupyter.org/.