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 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:

  • 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 Vector{Float64}:
  0.06858156600116058
 -0.39813709617338616
 -1.4667420739960741

to just

x = randn(10)
10-element Vector{Float64}:
  0.5933998865017774
  0.5163188712435195
 -0.2031573793216174
 -0.026398996439658783
  1.8456418255007208
  0.04136086010205985
  0.31742720349942327
 -1.958690880994408
  0.5397463453952518
  0.47070284102830906

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

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

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

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

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.