# 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.6681883287324164
-0.39121176021760123
-1.2621236362189332
```

to just

`x = randn(10)`

```
10-element Vector{Float64}:
0.8327266539755422
-1.0585143164290391
2.648073722248548
-0.11823595022208286
-1.4271596922029899
-1.8845153635402738
1.00148337200209
-0.9019312104971029
-1.0017883275558503
-0.6054070011303958
```

You can also use `@show`

or `println`

to show specific things beyond the last line

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

```
4.3911069632558215
5
```

if the last line is a `@show`

or `print`

then only that is shown:

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

```
x[1] = 0.8806294594828865
```

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:

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.