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:

  • the markdown is interpreted and evaluated

  • the code blocks are evaluated and their output can be shown selectively

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 MLJ Tutorials).

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:

  • suppress the output, in which case you should add a ; at the end of the line

  • only show a few elements (see below)

For instance you might prefer:

x = randn(10)
x[1:3]
3-element Array{Float64,1}:
 -0.49325828198406196
 -0.11552895278968883
  0.018491708391625016

to just

x = randn(10)
10-element Array{Float64,1}:
  0.6538616853497929
 -0.10593513912251445
  2.6489322943661775
 -1.717614333399003
  0.43801801468890345
  0.052267694249516765
 -1.245160083344675
 -0.58161923227242
 -0.6656390788021661
 -2.2307735228662136

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

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

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

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

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()

# #### Conclusion
#
# The equation 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.