Work with Literate.jl

Franklin works seamlessly with Literate to offer a convenient way to write and maintain tutorials.

Overview

Literate.jl is a convenient package that allows you to write scripts in Julia and convert them to markdown pages or Jupyter notebooks.

You can combine this with Franklin with the \literate command which you can call in Franklin like:

\literate{/_literate/script.jl}

it does what you expect:

If you want the script to be shown like a notebook where the output of every code block is shown, use @def showall = true.

Combining Franklin with Literate offers a very convenient way to write and maintain tutorial websites (see for instance the DataScienceTutorials).

File organisation

We recommend you have a folder /_literate/ in your root folder, place your literate scripts there and call them as in the example above.

Tricks

In the showall = true mode, the last line of each code block is displayed in full. In some cases you will have to think about this a bit more than you would in your REPL and might for instance:

For instance you might prefer:

x = randn(10)
x[1:3]

3-element Vector{Float64}:
 -0.28180837461866476
  0.8831090452668859
  0.22422101681348505

to just

x = randn(10)

10-element Vector{Float64}:
 -0.5593159701451623
  0.3660808732789371
  0.17401416928835736
  0.3933075307780431
 -1.1559540238134105
 -0.7104121307929046
 -0.7882963835903692
  0.6645555973082667
 -1.105414033812281
 -0.19011942269304533

You can also use @show or println to show specific things beyond the last line

x = rand(10)
println(sum(x))
y = 5

5.914418547027882
5

if the last line is a @show or print then only that is shown:

x = randn(10)
@show x[1]

x[1] = -1.642723241111864

The literate_mds = true mode adds support for using literal markdown strings, md""" ... """, for the markdown sections, a feature introduced in Literate v2.9. For example

md"""
# Title
something cool
"""

is rewritten to

# # Title
# something cool

Example

Script

# Some **really cool** maths:
#
# $$ \exp(i\pi) + 1 \quad = \quad 0 $$
#
# We can show this with some code:

x = exp(im*π) + 1

# that looks close to zero but

x ≈ 0

# however

abs(x) < eps()

md"""
#### Conclusion

The equation $ \exp(i\pi) + 1 \quad = \quad 0 $ is proven thanks to our very rigorous proof.
"""

Result

Some really cool maths:

\[ \exp(i\pi) + 1 \quad = \quad 0 \]

We can show this with some code:

x = exp(im*π) + 1

0.0 + 1.2246467991473532e-16im

that looks close to zero but

x ≈ 0

false

however

abs(x) < eps()

true

Conclusion

The equation is proven thanks to our very rigorous proof.