Changes to the whole template
|
@ -1,6 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
#hideall
|
||||
colors=(:pink, :lightpink, :hotpink, :deeppink, :mediumvioletred, :palevioletred, :coral, :tomato, :orangered, :darkorange, :orange, :gold, :yellow)
|
||||
print("@@ccols ")
|
||||
print.("\\circle{$c}" for c in colors)
|
||||
println("@@")
|
|
@ -1 +0,0 @@
|
|||
@@ccols \circle{pink}\circle{lightpink}\circle{hotpink}\circle{deeppink}\circle{mediumvioletred}\circle{palevioletred}\circle{coral}\circle{tomato}\circle{orangered}\circle{darkorange}\circle{orange}\circle{gold}\circle{yellow}@@
|
|
@ -1 +0,0 @@
|
|||
nothing
|
|
@ -1 +0,0 @@
|
|||
0.65
|
|
@ -1 +0,0 @@
|
|||
nothing
|
|
@ -1,19 +0,0 @@
|
|||
@@simple-table
|
||||
Name | Number
|
||||
:--- | :---
|
||||
Taimur | 1525
|
||||
Catherine | 5134
|
||||
Maria | 4214
|
||||
Arvind | 9019
|
||||
Jose | 8918
|
||||
Minjie | 5757
|
||||
@@
|
||||
~~~
|
||||
<style>
|
||||
.simple-table tr {
|
||||
padding:0;
|
||||
line-height:1em;
|
||||
}
|
||||
</style>
|
||||
~~~
|
||||
|
|
@ -1 +0,0 @@
|
|||
nothing
|
|
@ -1,77 +0,0 @@
|
|||
@@cards @@row
|
||||
@@column
|
||||
\card{Jane Doe}{CEO & Founder}{Phasellus eget enim eu lectus faucibus vestibulum}{example@example.com}
|
||||
@@
|
||||
|
||||
@@column
|
||||
\card{Mike Ross}{Art Director}{Phasellus eget enim eu lectus faucibus vestibulum}{example@example.com}
|
||||
@@
|
||||
|
||||
@@column
|
||||
\card{John Doe}{Designer}{Phasellus eget enim eu lectus faucibus vestibulum}{example@example.com}
|
||||
@@
|
||||
|
||||
@@ @@
|
||||
~~~
|
||||
<style>
|
||||
.column {
|
||||
float:left;
|
||||
width:30%;
|
||||
margin-bottom:16px;
|
||||
padding:0 8px;
|
||||
}
|
||||
@media (max-width:62rem) {
|
||||
.column {
|
||||
width:45%;
|
||||
display:block;
|
||||
}
|
||||
}
|
||||
@media (max-width:30rem){
|
||||
.column {
|
||||
width:95%;
|
||||
display:block;
|
||||
}
|
||||
}
|
||||
.card{
|
||||
box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2);
|
||||
}
|
||||
.card img {
|
||||
padding-left:0;
|
||||
width: 100%;
|
||||
}
|
||||
.container {
|
||||
padding: 0 16px;
|
||||
}
|
||||
.container::after, .row::after{
|
||||
content:"";
|
||||
clear:both;
|
||||
display:table;
|
||||
}
|
||||
.title {
|
||||
color:grey;
|
||||
}
|
||||
.vitae {
|
||||
margin-top:0.5em;
|
||||
}
|
||||
.email {
|
||||
font-family:courier;
|
||||
margin-top:0.5em;
|
||||
margin-bottom:0.5em;
|
||||
}
|
||||
.button{
|
||||
border:none;
|
||||
outline:0;
|
||||
display:inline-block;
|
||||
padding:8px;
|
||||
color:white;
|
||||
background-color:#000;
|
||||
text-align:center;
|
||||
cursor:pointer;
|
||||
width:100%;
|
||||
}
|
||||
.button:hover{
|
||||
background-color:#555;
|
||||
}
|
||||
</style>
|
||||
~~~
|
||||
|
|
@ -1 +0,0 @@
|
|||
nothing
|
|
@ -1,12 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
#hideall
|
||||
using PyCall
|
||||
lines = replace("""import numpy as np
|
||||
np.random.seed(2)
|
||||
x = np.random.randn(5)
|
||||
r = np.linalg.norm(x) / len(x)
|
||||
np.round(r, 2)""", r"(^|\n)([^\n]+)\n?$" => s"\1res = \2")
|
||||
py"""
|
||||
$$lines
|
||||
"""
|
||||
println(py"res")
|
|
@ -1,19 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
#hideall
|
||||
names = (:Taimur, :Catherine, :Maria, :Arvind, :Jose, :Minjie)
|
||||
numbers = (1525, 5134, 4214, 9019, 8918, 5757)
|
||||
println("@@simple-table")
|
||||
println("Name | Number")
|
||||
println(":--- | :---")
|
||||
println.("$name | $number" for (name, number) in zip(names, numbers))
|
||||
println("@@")
|
||||
raw"""
|
||||
~~~
|
||||
<style>
|
||||
.simple-table tr {
|
||||
padding:0;
|
||||
line-height:1em;
|
||||
}
|
||||
</style>
|
||||
~~~
|
||||
""" |> println
|
|
@ -1,82 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
#hideall
|
||||
team = [
|
||||
(name="Jane Doe", title="CEO & Founder", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com"),
|
||||
(name="Mike Ross", title="Art Director", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com"),
|
||||
(name="John Doe", title="Designer", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com")
|
||||
]
|
||||
|
||||
"@@cards @@row" |> println
|
||||
for person in team
|
||||
"""
|
||||
@@column
|
||||
\\card{$(person.name)}{$(person.title)}{$(person.vitae)}{$(person.email)}
|
||||
@@
|
||||
""" |> println
|
||||
end
|
||||
println("@@ @@") # end of cards + row
|
||||
|
||||
raw"""
|
||||
~~~
|
||||
<style>
|
||||
.column {
|
||||
float:left;
|
||||
width:30%;
|
||||
margin-bottom:16px;
|
||||
padding:0 8px;
|
||||
}
|
||||
@media (max-width:62rem) {
|
||||
.column {
|
||||
width:45%;
|
||||
display:block;
|
||||
}
|
||||
}
|
||||
@media (max-width:30rem){
|
||||
.column {
|
||||
width:95%;
|
||||
display:block;
|
||||
}
|
||||
}
|
||||
.card{
|
||||
box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2);
|
||||
}
|
||||
.card img {
|
||||
padding-left:0;
|
||||
width: 100%;
|
||||
}
|
||||
.container {
|
||||
padding: 0 16px;
|
||||
}
|
||||
.container::after, .row::after{
|
||||
content:"";
|
||||
clear:both;
|
||||
display:table;
|
||||
}
|
||||
.title {
|
||||
color:grey;
|
||||
}
|
||||
.vitae {
|
||||
margin-top:0.5em;
|
||||
}
|
||||
.email {
|
||||
font-family:courier;
|
||||
margin-top:0.5em;
|
||||
margin-bottom:0.5em;
|
||||
}
|
||||
.button{
|
||||
border:none;
|
||||
outline:0;
|
||||
display:inline-block;
|
||||
padding:8px;
|
||||
color:white;
|
||||
background-color:#000;
|
||||
text-align:center;
|
||||
cursor:pointer;
|
||||
width:100%;
|
||||
}
|
||||
.button:hover{
|
||||
background-color:#555;
|
||||
}
|
||||
</style>
|
||||
~~~
|
||||
""" |> println
|
|
@ -1,4 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
x = 5
|
||||
println("hello")
|
||||
x^2
|
|
@ -1 +0,0 @@
|
|||
hello
|
|
@ -1 +0,0 @@
|
|||
25
|
|
@ -1 +0,0 @@
|
|||
nothing
|
Before Width: | Height: | Size: 42 KiB |
|
@ -1,8 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
using PyPlot
|
||||
figure(figsize=(8, 6))
|
||||
x = range(-2, 2, length=500)
|
||||
for α in 1:5
|
||||
plot(x, sinc.(α .* x))
|
||||
end
|
||||
savefig(joinpath(@OUTPUT, "sinc.svg")) # hide
|
|
@ -1,2 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
x = randn(10)
|
|
@ -1,4 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
x = rand(10)
|
||||
println(sum(x))
|
||||
y = 5
|
|
@ -1,3 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
x = randn(10)
|
||||
@show x[1]
|
|
@ -1,2 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
x = exp(im*π) + 1
|
|
@ -1,2 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
x ≈ 0
|
|
@ -1,2 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
abs(x) < eps()
|
|
@ -1,11 +0,0 @@
|
|||
10-element Array{Float64,1}:
|
||||
-0.38675115697308454
|
||||
1.6354610234843316
|
||||
-1.2380735722784506
|
||||
-0.07027813689054306
|
||||
-1.5736602463947076
|
||||
0.6028777803673767
|
||||
0.907469270100251
|
||||
-0.0015565188581515314
|
||||
0.4464988414874392
|
||||
0.24990993606446546
|
|
@ -1 +0,0 @@
|
|||
5.418007222107764
|
|
@ -1 +0,0 @@
|
|||
5
|
|
@ -1 +0,0 @@
|
|||
x[1] = 0.33964471312600475
|
|
@ -1 +0,0 @@
|
|||
nothing
|
|
@ -1 +0,0 @@
|
|||
0.0 + 1.2246467991473532e-16im
|
|
@ -1 +0,0 @@
|
|||
false
|
|
@ -1 +0,0 @@
|
|||
true
|
|
@ -1,13 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
using PlotlyJS
|
||||
z = [10 10.625 12.5 15.625 20
|
||||
5.625 6.25 8.125 11.25 15.625
|
||||
2.5 3.125 5. 8.125 12.5
|
||||
0.625 1.25 3.125 6.25 10.625
|
||||
0 0.625 2.5 5.625 10]
|
||||
|
||||
data = contour(; z=z)
|
||||
layout = Layout(; title="Basic Contour Plot")
|
||||
plt = plot(data, layout)
|
||||
|
||||
fdplotly(json(plt)) # hide
|
|
@ -1,10 +0,0 @@
|
|||
~~~
|
||||
<div id="fdpdhq" style="width:600px;height:350px"></div>
|
||||
|
||||
<script>
|
||||
var fig = {"layout":{"margin":{"l":50,"b":50,"r":50,"t":60},"title":"Basic Contour Plot"},"data":[{"type":"contour","z":[[10.0,5.625,2.5,0.625,0.0],[10.625,6.25,3.125,1.25,0.625],[12.5,8.125,5.0,3.125,2.5],[15.625,11.25,8.125,6.25,5.625],[20.0,15.625,12.5,10.625,10.0]]}]};
|
||||
CONTAINER = document.getElementById('fdpdhq');
|
||||
Plotly.newPlot(CONTAINER, fig.data, fig.layout)
|
||||
</script>
|
||||
~~~
|
||||
|
|
@ -1 +0,0 @@
|
|||
nothing
|
Before Width: | Height: | Size: 32 KiB |
Before Width: | Height: | Size: 38 KiB |
Before Width: | Height: | Size: 90 KiB |
Before Width: | Height: | Size: 43 KiB |
Before Width: | Height: | Size: 40 KiB |
Before Width: | Height: | Size: 52 KiB |
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 1.4 KiB |
Before Width: | Height: | Size: 3.2 KiB |
Before Width: | Height: | Size: 5.6 KiB |
Before Width: | Height: | Size: 5.3 KiB |
|
@ -1 +0,0 @@
|
|||
<?xml version="1.0" ?><!DOCTYPE svg PUBLIC '-//W3C//DTD SVG 1.1//EN' 'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd'><svg height="32px" id="Layer_1" style="enable-background:new 0 0 32 32;" version="1.1" viewBox="0 0 32 32" width="32px" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><path d="M4,10h24c1.104,0,2-0.896,2-2s-0.896-2-2-2H4C2.896,6,2,6.896,2,8S2.896,10,4,10z M28,14H4c-1.104,0-2,0.896-2,2 s0.896,2,2,2h24c1.104,0,2-0.896,2-2S29.104,14,28,14z M28,22H4c-1.104,0-2,0.896-2,2s0.896,2,2,2h24c1.104,0,2-0.896,2-2 S29.104,22,28,22z"/></svg>
|
Before Width: | Height: | Size: 605 B |
|
@ -1 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 23"><path d="M5.1 14.8c0-.4.2-.7.5-.9-.2-.1-.4-.2-.5-.2-.5 0-.9.3-1.3.8s-.5 1.1-.5 1.8c0 1.2.5 2.2 1.4 3 .9.8 2.2 1.2 3.6 1.2 3.3 0 5.2-1.5 5.6-4.5.2-1.3.2-3 .2-5.2V4.5c0-1.6-.6-2.4-1.7-2.4-.3 0-.5 0-.7.1-.4.1-.7.1-.9.1-.3 0-.5-.1-.7-.3-.2-.3-.3-.5-.3-.8 0-.8.5-1.2 1.5-1.2h.5l1.8.2c.7.1 1.3.1 2.1.1.7 0 1.4-.1 2.2-.2l1.4-.1h.5c1 0 1.5.4 1.5 1.2 0 .7-.4 1.1-1.1 1.1-.2 0-.5 0-.9-.1-.2 0-.4-.1-.7-.1-1.1 0-1.7.8-1.7 2.4v6.3c0 3.3-.1 5.5-.4 6.6-.2 1-.7 1.9-1.5 2.7-1.6 1.8-3.8 2.7-6.5 2.7-2.3 0-4.2-.6-5.6-1.8C1.5 19.8.7 18.2.7 16.4c0-1.4.4-2.6 1.3-3.6s2-1.4 3.3-1.4c.9 0 1.7.2 2.3.7.6.5.9 1.1.9 1.9 0 .6-.2 1-.5 1.4-.4.4-.8.6-1.3.6-.4 0-.8-.1-1.1-.4-.3-.1-.5-.4-.5-.8zM35.3 21.4v-1c-1.2 1.6-2.9 2.4-5.2 2.4-2.6 0-4.4-.8-5.4-2.4-.4-.7-.7-1.5-.7-2.5v-5.6c0-3-.3-4.5-1-4.5H21.7c-.8 0-1.2-.4-1.2-1.1 0-.7.5-1 1.4-1 .2 0 .5 0 1 .1.4.1.8.1 1 .1.2 0 .5 0 1-.1.3 0 .5-.1.6-.1.7 0 1 .4 1 1.3v2.8l-.1 2.4v2.1c0 1.9.2 3.3.5 4.1.5 1.4 1.7 2.1 3.6 2.1.9 0 1.8-.2 2.5-.6.7-.4 1.2-1 1.5-1.7.4-.9.5-2.5.5-4.9v-1.8-2.1c-.1-1.1-.4-1.6-.9-1.6h-1c-.8 0-1.2-.3-1.2-1s.4-1.1 1.3-1.1c.2 0 .5 0 .9.1.4 0 .7.1.9.1.2 0 .4 0 .8-.1.4 0 .6-.1.8-.1.7 0 1 .4 1 1.1 0 .3 0 .6-.1.7-.1.8-.2 2.1-.2 3.7V18.6c.1 1.2.4 1.8.9 1.8.2 0 .4 0 .7-.1.3-.1.5-.1.7-.1.7 0 1.1.4 1.1 1.1 0 .8-.5 1.1-1.4 1.1-.2 0-.5 0-.9-.1-.6-.1-.9-.1-1-.1-.1 0-.3 0-.7.1-.3.1-.5.1-.7.1-.4-.1-.7-.4-.7-1zM45.9 4.5c0-1.7-.6-2.5-1.7-2.5-.2 0-.4 0-.7.1-.4.1-.7.1-.9.1-.7 0-1-.4-1-1.1 0-.8.5-1.2 1.5-1.2h.4l1.8.2c.7.1 1.4.1 2.1.1.6 0 1.2 0 1.9-.1l2.1-.2c.4.1 1 .1 1.6.1 2 0 3.7.3 5 .9 1.8.8 3.2 2.1 4.2 3.9 1 1.9 1.5 4 1.5 6.4 0 2.2-.4 4.1-1.2 5.8-.8 1.7-1.9 3-3.3 3.8-1.7 1-3.7 1.5-6.2 1.5-.5 0-1 0-1.5-.1l-2.3-.2h-2.3c-.7 0-1.3 0-1.8.1l-1.6.2H43c-.9 0-1.4-.4-1.4-1.2 0-.3.1-.6.3-.8.2-.2.4-.3.7-.3.2 0 .5 0 .9.1.2 0 .4.1.7.1 1.1 0 1.7-.8 1.7-2.5V4.5zm2.8-.3v13.9c0 1 .5 1.6 1.5 1.8.3.1 1.3.1 2.8.1 2.6 0 4.6-.7 5.8-2.1 1.4-1.7 2.1-4 2.1-6.8 0-2.2-.4-4.1-1.3-5.6S57.5 3.1 56 2.7c-1-.3-2.1-.4-3.5-.4-1.7 0-2.8.1-3.2.3-.4.1-.6.7-.6 1.6zM73.9 22.8c-2.3 0-4.2-.8-5.6-2.4s-2.1-3.7-2.1-6.4.7-4.8 2.1-6.4c1.4-1.6 3.3-2.4 5.6-2.4 2.4 0 4.3.8 5.7 2.3 1.4 1.6 2.1 3.7 2.1 6.4s-.7 4.8-2.1 6.5c-1.4 1.6-3.3 2.4-5.7 2.4zm.2-15.5c-1.5 0-2.8.5-3.6 1.6-.9 1.1-1.4 2.6-1.5 4.6v.4c0 2.1.4 3.7 1.3 4.9s2.1 1.8 3.7 1.8 2.9-.6 3.8-1.8 1.4-2.8 1.4-4.9c-.1-4.4-1.8-6.6-5.1-6.6zM94 11.3c0-.9.6-1.4 1.7-1.5-.2-.8-.5-1.4-1.2-1.8-.6-.4-1.4-.7-2.4-.7-1.5 0-2.7.6-3.7 1.8S87 11.9 87 13.9c0 2.1.4 3.7 1.3 4.9s2.1 1.8 3.6 1.8c1 0 1.8-.3 2.5-.8.7-.6 1.2-1.3 1.5-2.3.2-.8.4-1.2.4-1.3.2-.4.6-.7 1.1-.7.4 0 .7.1.9.4.2.2.4.6.4.9 0 .6-.2 1.2-.5 2-.4.8-.8 1.4-1.3 1.9-1.3 1.4-3 2.1-5.1 2.1-2.2 0-4.1-.8-5.4-2.4-1.4-1.6-2.1-3.7-2.1-6.2 0-2.7.7-4.9 2.1-6.6 1.4-1.6 3.3-2.5 5.7-2.5 1.8 0 3.2.5 4.4 1.4s1.8 2.2 1.8 3.7c0 .8-.2 1.5-.7 2-.5.5-1 .8-1.7.8-.6 0-1-.2-1.4-.5-.3-.3-.5-.7-.5-1.2z"/></svg>
|
Before Width: | Height: | Size: 2.8 KiB |
Before Width: | Height: | Size: 59 KiB |
Before Width: | Height: | Size: 893 B |
|
@ -1 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 50"><path d="M9.4 36.7V26.2c0-2.1-.7-3.2-2.2-3.2-.4 0-.7 0-.9.1-.5.1-.8.2-1.1.2-.4 0-.7-.1-.9-.4-.3-.3-.4-.6-.4-1 0-1 .6-1.6 1.8-1.6h.6l3 .3c1.1.1 2.4.2 3.8.2.7 0 2.4 0 4.8-.1l5-.2c.7 0 1.4-.1 2.3-.1.4-.1.8-.1 1.3-.1 1.5 0 2.3.7 2.3 2 0 .5-.1 1.3-.2 2.4-.1 1.1-.2 1.9-.2 2.4s0 1 .1 1.7.1 1.3.1 1.9c0 1.2-.5 1.8-1.6 1.8s-1.6-.7-1.6-2c0-.4 0-1 .1-1.8s.1-1.4.1-1.8c0-1.5-.4-2.5-1.3-2.9-.9-.4-2.9-.6-6.1-.6-2.7 0-4.3.2-4.7.7-.3.4-.4 1.7-.4 4v3.2c0 .8.1 1.3.3 1.5.2.2.8.3 1.8.3h1.4c1.9 0 2.8-.7 2.8-2.1 0-.3 0-.7-.1-1.3-.1-.5-.1-1-.1-1.3 0-1.1.5-1.6 1.6-1.6 1 0 1.5.6 1.5 1.9 0 .2 0 .5-.1 1l-.4 2.3c-.1 1-.2 1.8-.2 2.3 0 1.2.2 2.7.5 4.5.1.6.2 1.2.2 1.7 0 1.1-.5 1.7-1.6 1.7-1 0-1.5-.6-1.5-1.8 0-.3 0-.7.1-1.3 0-.6.1-1 .1-1.3 0-.9-.2-1.5-.7-1.7-.3-.2-1-.3-2-.3h-1.3c-1 0-1.6.1-1.9.3-.4.3-.5.9-.5 2v5.1c0 1.3.2 2.2.5 2.7s.9.7 1.7.7H17c1.3 0 2 .5 2 1.5 0 .4-.2.7-.5 1-.3.3-.7.4-1.1.4-.5 0-1.1-.1-2-.2-1.3-.2-2.7-.3-4.3-.3-1 0-2.1.1-3.3.3l-1.5.2h-.6c-1.3 0-1.9-.5-1.9-1.6 0-.9.4-1.4 1.3-1.4.1 0 .5 0 1.1.1.3.1.6.1.9.1.8 0 1.3-.2 1.6-.7s.5-1.3.5-2.5v-6.8z" fill="#3e4fa2"/><path d="M15.1 2.8c-2.3 1.6-3 1.8-5.2 1.5-3.6-.5-4.9-.1-5.4 1.6-.3 1-.4 3.1-.3 6 0 1.6 0 2.5-.1 2.8-.1.2-.8.9-1.7 1.6-.8.6-1.7 1.3-1.8 1.5-.3.4-.3 1 .1 1 .1 0 7.1-1.3 15.4-2.9 16.5-3.2 15.8-3 15.6-3.8-.1-.4-.9-.9-1.6-.9-.3 0-1 0-1.5-.1-1.8-.1-2.7-.8-3.5-2.5-1.5-3.5-3.1-6.5-4-7.5-.3-.3-.7-.6-1-.7-1-.1-2.1.4-5 2.4z" fill="#020202"/></svg>
|
Before Width: | Height: | Size: 1.4 KiB |
|
@ -1 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 50"><path d="M15.1 2.8c-2.3 1.6-3 1.8-5.2 1.5-3.6-.5-4.9-.1-5.4 1.6-.3 1-.4 3.1-.3 6 0 1.6 0 2.5-.1 2.8-.1.2-.8.9-1.7 1.6-.8.6-1.7 1.3-1.8 1.5-.3.4-.3 1 .1 1 .1 0 7.1-1.3 15.4-2.9 16.5-3.2 15.8-3 15.6-3.8-.1-.4-.9-.9-1.6-.9-.3 0-1 0-1.5-.1-1.8-.1-2.7-.8-3.5-2.5-1.5-3.5-3.1-6.5-4-7.5-.3-.3-.7-.6-1-.7-1-.1-2.1.4-5 2.4z" fill="#030303"/><path d="M9.3 36.6V26.2c0-2.1-.7-3.2-2.2-3.2-.4 0-.7 0-.8.1-.5.1-.8.2-1.1.2-.4 0-.7-.1-.9-.4-.3-.3-.4-.6-.4-1 0-1 .6-1.5 1.8-1.5h.6l3 .3c1.1.1 2.4.2 3.7.2.7 0 2.3 0 4.8-.1l4.9-.2c.7 0 1.4-.1 2.3-.1.4-.1.8-.1 1.3-.1 1.5 0 2.3.7 2.3 2 0 .5-.1 1.3-.2 2.4-.1 1.1-.2 1.9-.2 2.4s0 1 .1 1.7.1 1.3.1 1.9c0 1.2-.5 1.8-1.5 1.8-1.1 0-1.6-.7-1.6-2 0-.4 0-1 .1-1.8s.1-1.4.1-1.8c0-1.5-.4-2.5-1.3-2.9-.9-.4-2.9-.6-6.1-.6-2.7 0-4.3.2-4.6.7-.3.4-.4 1.7-.4 3.9v3.2c0 .8.1 1.3.3 1.5s.8.3 1.8.3h1.4c1.9 0 2.8-.7 2.8-2.1 0-.3 0-.7-.1-1.3-.3-.7-.3-1.1-.3-1.4 0-1.1.5-1.6 1.5-1.6s1.5.6 1.5 1.9c0 .2 0 .5-.1 1l-.3 2.3c-.1 1-.2 1.8-.2 2.3 0 1.2.2 2.7.4 4.5.1.6.2 1.2.2 1.7 0 1.1-.5 1.7-1.5 1.7s-1.5-.6-1.5-1.8c0-.3 0-.7.1-1.3 0-.6.1-1 .1-1.3 0-.9-.2-1.5-.7-1.7-.3-.2-1-.3-2-.3h-1.3c-1 0-1.6.1-1.8.3-.2.2-.3.8-.3 1.9V43c0 1.3.1 2.2.4 2.7.3.5.9.7 1.7.7H17c1.3 0 2 .5 2 1.5 0 .4-.1.7-.4 1-.3.3-.7.4-1.1.4-.5 0-1.1-.1-2-.2-1.3-.2-2.7-.3-4.3-.3-1 0-2.1.1-3.3.3l-1.5.2h-.6c-1.3 0-1.9-.5-1.9-1.5 0-.9.4-1.4 1.3-1.4.1 0 .5 0 1.1.1.3.1.6.1.9.1.8 0 1.3-.2 1.6-.7.3-.5.5-1.3.5-2.5v-6.8z" fill="#3f50a2"/></svg>
|
Before Width: | Height: | Size: 1.4 KiB |
Before Width: | Height: | Size: 1.1 KiB |
|
@ -1,37 +0,0 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- Generator: Adobe Illustrator 19.2.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
|
||||
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
|
||||
viewBox="0 0 50 50" style="enable-background:new 0 0 50 50;" xml:space="preserve">
|
||||
<style type="text/css">
|
||||
.st0{fill:#3F50A2;}
|
||||
.st1{fill:#030303;}
|
||||
</style>
|
||||
<path class="st0" d="M18.4,36.7V26.2c0-2.1-0.7-3.2-2.2-3.2c-0.4,0-0.7,0-0.9,0.1c-0.5,0.1-0.8,0.2-1.1,0.2c-0.4,0-0.7-0.1-0.9-0.4
|
||||
c-0.3-0.3-0.4-0.6-0.4-1c0-1,0.6-1.6,1.8-1.6h0.6l3,0.3c1.1,0.1,2.4,0.2,3.8,0.2c0.7,0,2.4,0,4.8-0.1l5-0.2c0.7,0,1.4-0.1,2.3-0.1
|
||||
c0.4-0.1,0.8-0.1,1.3-0.1c1.5,0,2.3,0.7,2.3,2c0,0.5-0.1,1.3-0.2,2.4c-0.1,1.1-0.2,1.9-0.2,2.4s0,1,0.1,1.7s0.1,1.3,0.1,1.9
|
||||
c0,1.2-0.5,1.8-1.6,1.8s-1.6-0.7-1.6-2c0-0.4,0-1,0.1-1.8s0.1-1.4,0.1-1.8c0-1.5-0.4-2.5-1.3-2.9c-0.9-0.4-2.9-0.6-6.1-0.6
|
||||
c-2.7,0-4.3,0.2-4.7,0.7c-0.3,0.4-0.4,1.7-0.4,4v3.2c0,0.8,0.1,1.3,0.3,1.5s0.8,0.3,1.8,0.3h1.4c1.9,0,2.8-0.7,2.8-2.1
|
||||
c0-0.3,0-0.7-0.1-1.3c-0.1-0.5-0.1-1-0.1-1.3c0-1.1,0.5-1.6,1.6-1.6c1,0,1.5,0.6,1.5,1.9c0,0.2,0,0.5-0.1,1L30.8,32
|
||||
c-0.1,1-0.2,1.8-0.2,2.3c0,1.2,0.2,2.7,0.5,4.5c0.1,0.6,0.2,1.2,0.2,1.7c0,1.1-0.5,1.7-1.6,1.7c-1,0-1.5-0.6-1.5-1.8
|
||||
c0-0.3,0-0.7,0.1-1.3c0-0.6,0.1-1,0.1-1.3c0-0.9-0.2-1.5-0.7-1.7c-0.3-0.2-1-0.3-2-0.3h-1.3c-1,0-1.6,0.1-1.9,0.3
|
||||
c-0.4,0.3-0.5,0.9-0.5,2v5.1c0,1.3,0.2,2.2,0.5,2.7c0.3,0.5,0.9,0.7,1.7,0.7H26c1.3,0,2,0.5,2,1.5c0,0.4-0.2,0.7-0.5,1
|
||||
s-0.7,0.4-1.1,0.4c-0.5,0-1.1-0.1-2-0.2c-1.3-0.2-2.7-0.3-4.3-0.3c-1,0-2.1,0.1-3.3,0.3l-1.5,0.2h-0.6c-1.3,0-1.9-0.5-1.9-1.6
|
||||
c0-0.9,0.4-1.4,1.3-1.4c0.1,0,0.5,0,1.1,0.1c0.3,0.1,0.6,0.1,0.9,0.1c0.8,0,1.3-0.2,1.6-0.7c0.3-0.5,0.5-1.3,0.5-2.5v-6.8L18.4,36.7
|
||||
z"/>
|
||||
<path class="st1" d="M24.1,2.8c-2.3,1.6-3,1.8-5.2,1.5c-3.6-0.5-4.9-0.1-5.4,1.6c-0.3,1-0.4,3.1-0.3,6c0,1.6,0,2.5-0.1,2.8
|
||||
c-0.1,0.2-0.8,0.9-1.7,1.6c-0.8,0.6-1.7,1.3-1.8,1.5c-0.3,0.4-0.3,1,0.1,1c0.1,0,7.1-1.3,15.4-2.9c16.5-3.2,15.8-3,15.6-3.8
|
||||
c-0.1-0.4-0.9-0.9-1.6-0.9c-0.3,0-1,0-1.5-0.1c-1.8-0.1-2.7-0.8-3.5-2.5c-1.5-3.5-3.1-6.5-4-7.5c-0.3-0.3-0.7-0.6-1-0.7
|
||||
C28.1,0.3,27,0.8,24.1,2.8z"/>
|
||||
<g>
|
||||
</g>
|
||||
<g>
|
||||
</g>
|
||||
<g>
|
||||
</g>
|
||||
<g>
|
||||
</g>
|
||||
<g>
|
||||
</g>
|
||||
<g>
|
||||
</g>
|
||||
</svg>
|
Before Width: | Height: | Size: 2.1 KiB |
|
@ -1 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50"><path d="M23.1 2.8c-2.3 1.6-3 1.8-5.2 1.5-3.6-.5-4.9-.1-5.4 1.6-.3 1-.4 3.1-.3 6 0 1.6 0 2.5-.1 2.8-.1.2-.8.9-1.7 1.6-.8.6-1.7 1.3-1.8 1.5-.3.4-.3 1 .1 1 .1 0 7.1-1.3 15.4-2.9 16.5-3.2 15.8-3 15.6-3.8-.1-.4-.9-.9-1.6-.9-.3 0-1 0-1.5-.1-1.8-.1-2.7-.8-3.5-2.5-1.5-3.5-3.1-6.5-4-7.5-.3-.3-.7-.6-1-.7-1-.1-2.1.4-5 2.4z" fill="#030303"/><path d="M17.3 36.6V26.2c0-2.1-.7-3.2-2.2-3.2-.4 0-.7 0-.8.1-.5.1-.8.2-1.1.2-.4 0-.7-.1-.9-.4-.3-.3-.4-.6-.4-1 0-1 .6-1.5 1.8-1.5h.6l3 .3c1.1.1 2.4.2 3.7.2.7 0 2.3 0 4.8-.1l4.9-.2c.7 0 1.4-.1 2.3-.1.4-.1.8-.1 1.3-.1 1.5 0 2.3.7 2.3 2 0 .5-.1 1.3-.2 2.4-.1 1.1-.2 1.9-.2 2.4s0 1 .1 1.7.1 1.3.1 1.9c0 1.2-.5 1.8-1.5 1.8-1.1 0-1.6-.7-1.6-2 0-.4 0-1 .1-1.8s.1-1.4.1-1.8c0-1.5-.4-2.5-1.3-2.9-.9-.4-2.9-.6-6.1-.6-2.7 0-4.3.2-4.6.7-.3.4-.4 1.7-.4 3.9v3.2c0 .8.1 1.3.3 1.5s.8.3 1.8.3h1.4c1.9 0 2.8-.7 2.8-2.1 0-.3 0-.7-.1-1.3-.3-.7-.3-1.1-.3-1.4 0-1.1.5-1.6 1.5-1.6s1.5.6 1.5 1.9c0 .2 0 .5-.1 1l-.3 2.3c-.1 1-.2 1.8-.2 2.3 0 1.2.2 2.7.4 4.5.1.6.2 1.2.2 1.7 0 1.1-.5 1.7-1.5 1.7s-1.5-.6-1.5-1.8c0-.3 0-.7.1-1.3 0-.6.1-1 .1-1.3 0-.9-.2-1.5-.7-1.7-.3-.2-1-.3-2-.3h-1.3c-1 0-1.6.1-1.8.3-.2.2-.3.8-.3 1.9V43c0 1.3.1 2.2.4 2.7.3.5.9.7 1.7.7H25c1.3 0 2 .5 2 1.5 0 .4-.1.7-.4 1-.3.3-.7.4-1.1.4-.5 0-1.1-.1-2-.2-1.3-.2-2.7-.3-4.3-.3-1 0-2.1.1-3.3.3l-1.5.2h-.6c-1.3 0-1.9-.5-1.9-1.5 0-.9.4-1.4 1.3-1.4.1 0 .5 0 1.1.1.3.1.6.1.9.1.8 0 1.3-.2 1.6-.7.3-.5.5-1.3.5-2.5v-6.8z" fill="#3f50a2"/></svg>
|
Before Width: | Height: | Size: 1.4 KiB |
Before Width: | Height: | Size: 18 KiB |
Before Width: | Height: | Size: 121 KiB |
Before Width: | Height: | Size: 34 KiB |
Before Width: | Height: | Size: 72 KiB |
Before Width: | Height: | Size: 69 KiB |
|
@ -1,27 +0,0 @@
|
|||
<!--This file was generated, do not modify it.-->
|
||||
Some **really cool** maths:
|
||||
|
||||
$$ \exp(i\pi) + 1 \quad = \quad 0 $$
|
||||
|
||||
We can show this with some code:
|
||||
|
||||
```julia:ex1
|
||||
x = exp(im*π) + 1
|
||||
```
|
||||
|
||||
that looks close to zero but
|
||||
|
||||
```julia:ex2
|
||||
x ≈ 0
|
||||
```
|
||||
|
||||
however
|
||||
|
||||
```julia:ex3
|
||||
abs(x) < eps()
|
||||
```
|
||||
|
||||
#### Conclusion
|
||||
|
||||
The equation is proven thanks to our very rigorous proof.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
# This file was generated, do not modify it.
|
||||
|
||||
x = exp(im*π) + 1
|
||||
|
||||
x ≈ 0
|
||||
|
||||
abs(x) < eps()
|
||||
|
|
@ -1 +0,0 @@
|
|||
3.173
|
|
@ -1,5 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
using LinearAlgebra, Random
|
||||
Random.seed!(555)
|
||||
a = randn(5)
|
||||
round(norm(a), sigdigits=4)
|
|
@ -1,5 +0,0 @@
|
|||
# This file was generated, do not modify it. # hide
|
||||
using PyPlot
|
||||
figure()
|
||||
plot([0, 1], [0, 1])
|
||||
savefig(joinpath(@OUTPUT, "test.png"))
|
|
@ -1 +0,0 @@
|
|||
nothing
|
Before Width: | Height: | Size: 17 KiB |
30
_css/jtd.css
|
@ -73,7 +73,8 @@ code{
|
|||
line-height:1.4;
|
||||
padding:0.2em 0.15em;
|
||||
font-weight:400;
|
||||
background-color:#f5f6fa;
|
||||
/*background-color:#f5f6fa;*/
|
||||
background-color: #ffffff;
|
||||
border:1px solid #eeebee;
|
||||
border-radius:4px;
|
||||
}
|
||||
|
@ -118,7 +119,7 @@ SIDE BAR
|
|||
z-index: 100;
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
background-color:#f5f6fa;
|
||||
background-color: #b9cfe4;
|
||||
}
|
||||
.side-bar .header {
|
||||
display: flex;
|
||||
|
@ -244,9 +245,11 @@ input[type=checkbox]:checked ~ #side-menu{display: block;}
|
|||
.side-bar .menu {
|
||||
display: none;
|
||||
padding-left:35px;
|
||||
padding-bottom:15px;}
|
||||
padding-bottom:15px;
|
||||
}
|
||||
.side-bar {
|
||||
border-bottom: 1px solid #eeebee;
|
||||
background-color: #b9cfe4;
|
||||
}
|
||||
.side-bar .header {
|
||||
padding-left: 15px;
|
||||
|
@ -298,7 +301,8 @@ input[type=checkbox]:checked ~ #side-menu{display: block;}
|
|||
padding-top:3rem;
|
||||
padding-bottom:1rem;
|
||||
overflow-y:auto;
|
||||
flex:1 1 auto
|
||||
flex:1 1 auto;
|
||||
/*background-color: #0E39B0;*/
|
||||
}
|
||||
.side-bar .footer{
|
||||
padding-right:2rem;
|
||||
|
@ -332,7 +336,8 @@ MAIN CONTENT
|
|||
height: 100%;
|
||||
-webkit-overflow-scrolling: touch;
|
||||
overflow-x: hidden;
|
||||
overflow-y: scroll
|
||||
overflow-y: scroll;
|
||||
background-color: #e8ecef;
|
||||
}
|
||||
.main-content{
|
||||
position:relative;
|
||||
|
@ -352,14 +357,15 @@ MAIN CONTENT
|
|||
display:none;
|
||||
/* padding-top:1rem; */
|
||||
/* padding-bottom:1rem; */
|
||||
background-color:#f5f6fa;
|
||||
background-color: #e8ecef;
|
||||
height: 60px;
|
||||
line-height: 60px;
|
||||
}
|
||||
@media (min-width: 50rem){
|
||||
.main-header{
|
||||
padding-right:2rem;
|
||||
padding-left:2rem
|
||||
padding-left:2rem;
|
||||
background-color: #e8ecef;
|
||||
}
|
||||
}
|
||||
@media (min-width: 50rem){
|
||||
|
@ -367,7 +373,7 @@ MAIN CONTENT
|
|||
display:flex;
|
||||
justify-content:flex-end;
|
||||
height: -1em;
|
||||
background-color:#fff;
|
||||
background-color: #e8ecef;
|
||||
border-bottom:1px solid #eeebee;
|
||||
}
|
||||
}
|
||||
|
@ -610,7 +616,7 @@ ul.menu-list-child-list a.menu-list-link {
|
|||
}
|
||||
|
||||
#lunrSearchForm {
|
||||
margin-top: 1em;
|
||||
margin-top: 13em;
|
||||
}
|
||||
|
||||
/* .pagination {
|
||||
|
@ -745,3 +751,9 @@ ul.menu-list-child-list a.menu-list-link {
|
|||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
}
|
||||
|
||||
#title-header {
|
||||
margin-top: -1.9em;
|
||||
margin-right: 2em;
|
||||
color: #6b7a99;
|
||||
}
|
||||
|
|
|
@ -6,7 +6,7 @@
|
|||
{{if hasmath}} {{insert head_katex.html }} {{end}}
|
||||
{{if hascode}} {{insert head_highlight.html }} {{end}}
|
||||
<link rel="stylesheet" href="/css/jtd.css">
|
||||
<link rel="icon" href="/assets/infra/logoF_square.gif">
|
||||
<link rel="icon" href="/assets/infra/favicon.ico">
|
||||
{{isdef title}} <title>{{fill title}}</title> {{end}}
|
||||
|
||||
<!-- LUNR -->
|
||||
|
@ -24,7 +24,8 @@
|
|||
<div class="side-bar">
|
||||
<div class="header">
|
||||
<a href="/" class="title">
|
||||
<!-- <img style="height:60px;" src="/assets/infra/franklin.svg" alt="franklin" /> -->
|
||||
<img style="height:60px;" src="/assets/infra/franklin.svg" alt="BLOG" />
|
||||
|
||||
<style>
|
||||
@media (max-width: 31.25rem){
|
||||
.side-bar .show-menu {height:30px;}
|
||||
|
@ -46,56 +47,36 @@
|
|||
<!-- HOME -->
|
||||
<li class="menu-list-item {{ispage index}}active{{end}}"><a href="/" class="menu-list-link">• Home</a>
|
||||
<!-- WORKFLOW -->
|
||||
<li class="menu-list-parent {{ispage workflow/*}}active{{end}}"><a href="/workflow/" class="menu-list-link">• Workflow</a>
|
||||
<ul class="menu-list-child-list ">
|
||||
<li class="menu-list-item {{ispage workflow/index.html}}active{{end}}"><a href="/workflow/" class="menu-list-link">Create and edit</a>
|
||||
<li class="menu-list-item {{ispage workflow/structure}}active{{end}}"><a href="/workflow/structure/" class="menu-list-link">Page structure</a>
|
||||
<li class="menu-list-item {{ispage workflow/deploy}}active{{end}}"><a href="/workflow/deploy/" class="menu-list-link">Deploy</a>
|
||||
</ul>
|
||||
<!-- SYNTAX -->
|
||||
<!-- NOTE: if adding a menu item, add ref to first item! -->
|
||||
<li class="menu-list-parent {{ispage syntax/*}}active{{end}}"><a href="/syntax/markdown/" class="menu-list-link">• Syntax</a>
|
||||
<ul class="menu-list-child-list ">
|
||||
<li class="menu-list-item {{ispage syntax/markdown}}active{{end}}"><a href="/syntax/markdown/" class="menu-list-link">Markdown</a>
|
||||
<li class="menu-list-item {{ispage syntax/divs-commands}}active{{end}}"><a href="/syntax/divs-commands/" class="menu-list-link">Divs and Commands</a>
|
||||
<li class="menu-list-item {{ispage syntax/page-variables}}active{{end}}"><a href="/syntax/page-variables/" class="menu-list-link">Page Variables</a>
|
||||
<li class="menu-list-item {{ispage syntax/utils}}active{{end}}"><a href="/syntax/utils/" class="menu-list-link">Utils</a>
|
||||
</ul>
|
||||
<!-- STYLING -->
|
||||
<li class="menu-list-parent {{ispage styling/*}}active{{end}}"><a href="/styling/templates/" class="menu-list-link">• Styling</a>
|
||||
<ul class="menu-list-child-list ">
|
||||
<li class="menu-list-item {{ispage styling/templates}}active{{end}}"><a href="/styling/templates/" class="menu-list-link">Templates</a>
|
||||
<li class="menu-list-item {{ispage styling/classes}}active{{end}}"><a href="/styling/classes/" class="menu-list-link">Classes</a>
|
||||
</ul>
|
||||
<!-- CODE -->
|
||||
<li class="menu-list-parent {{ispage code/*}}active{{end}}"><a href="/code/" class="menu-list-link">• Code</a>
|
||||
<ul class="menu-list-child-list ">
|
||||
<li class="menu-list-item {{ispage projects/*}}active{{end}}"><a href="/projects/" class="menu-list-link">• Projects</a>
|
||||
<!-- CODE (class="menu-list-parent") -->
|
||||
<li class="menu-list-item {{ispage cv/*}}active{{end}}"><a href="/cv/" class="menu-list-link">• CV</a>
|
||||
<!-- <ul class="menu-list-child-list ">
|
||||
<li class="menu-list-item {{ispage code/index.html}}active{{end}}"><a href="/code/" class="menu-list-link">Inserting code</a>
|
||||
<li class="menu-list-item {{ispage code/eval-tricks}}active{{end}}"><a href="/code/eval-tricks/" class="menu-list-link">Code tricks</a>
|
||||
<li class="menu-list-item {{ispage code/literate}}active{{end}}"><a href="/code/literate/" class="menu-list-link">Literate.jl</a>
|
||||
</ul>
|
||||
</ul> -->
|
||||
<!-- EXTRAs -->
|
||||
<li class="menu-list-parent {{ispage extras/*}}active{{end}}"><a href="/extras/" class="menu-list-link">• Extras</a>
|
||||
<!-- <li class="menu-list-parent {{ispage extras/*}}active{{end}}"><a href="/extras/" class="menu-list-link">• Extras</a>
|
||||
<ul class="menu-list-child-list ">
|
||||
<li class="menu-list-item {{ispage extras/index.html}}active{{end}}"><a href="/extras/" class="menu-list-link">Overview</a>
|
||||
<li class="menu-list-item {{ispage extras/lunr}}active{{end}}"><a href="/extras/lunr/" class="menu-list-link">Lunr search</a>
|
||||
<li class="menu-list-item {{ispage extras/literate}}active{{end}}"><a href="/extras/literate/" class="menu-list-link">Literate</a>
|
||||
<li class="menu-list-item {{ispage extras/plotly}}active{{end}}"><a href="/extras/plotly/" class="menu-list-link">Plotly</a>
|
||||
</ul>
|
||||
</ul> -->
|
||||
<!-- FAQ -->
|
||||
<li class="menu-list-parent {{ispage faq/*}}active{{end}}"><a href="/faq/technical/" class="menu-list-link">• FAQ</a>
|
||||
<ul class="menu-list-child-list ">
|
||||
<li class="menu-list-item {{ispage faq/*}}active{{end}}"><a href="/faq/technical/" class="menu-list-link">• FAQ</a>
|
||||
<!-- <ul class="menu-list-child-list ">
|
||||
<li class="menu-list-item {{ispage faq/technical}}active{{end}}"><a href="/faq/technical/" class="menu-list-link">Technical</a>
|
||||
<li class="menu-list-item {{ispage faq/troubleshooting}}active{{end}}"><a href="/faq/troubleshooting/" class="menu-list-link">Troubleshooting</a>
|
||||
<li class="menu-list-item {{ispage faq/why-o-why}}active{{end}}"><a href="/faq/why-o-why/" class="menu-list-link">Meta</a>
|
||||
</ul>
|
||||
</ul>-->
|
||||
</ul>
|
||||
<form id="lunrSearchForm" name="lunrSearchForm">
|
||||
<input class="search-input" name="q" placeholder="Enter search term" type="text"> <input type="submit" value="Search" formaction="/search/index.html">
|
||||
</form>
|
||||
</div>
|
||||
<div class="footer">
|
||||
<a href="/faq/why-o-why/"><img style="width:40%;padding-left:10px;margin-bottom:15px;" src="/assets/infra/logoF2.svg" alt="Franklin Logo" /></a>
|
||||
<a href="/faq/why-o-why/"><img style="width:40%;padding-left:10px;margin-bottom:15px;" src="/assets/infra/lambda.png" alt="Lambda" /></a>
|
||||
</div>
|
||||
</div>
|
||||
<!-- CONTENT -->
|
||||
|
@ -105,7 +86,7 @@
|
|||
<a name="pagetop"></a>
|
||||
|
||||
<!-- <a id="github" href="https://github.com/tlienart/franklindocs/blob/master/{{fd_rpath}}">Page source</a> -->
|
||||
<a id="github"><h1>A Neural Network Developer</h1></a>
|
||||
<a id="title-header"><h1>A Neural Network Developer</h1></a>
|
||||
<span style="width:30px; text-align: center;color:lightgray;">|</span>
|
||||
<a id="github" href="https://github.com/EddieCueto/">GitHub Repository</a>
|
||||
</div>
|
||||
|
|
|
@ -1,417 +0,0 @@
|
|||
<!--
|
||||
reviewed: 22/12/2019
|
||||
-->
|
||||
|
||||
@def hascode=true
|
||||
|
||||
# Tricks with code evaluation
|
||||
|
||||
\blurb{Franklin's recursive nature coupled with code evaluation allows for neat and useful tricks.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
The basic idea is to exploit the fact that the output of a Julia code block evaluated by Franklin can be re-processed as Franklin Markdow when using the `\textoutput` command; this offers a wide range of possibilities best shown through a few examples (more or less in increasing degree of sophistication).
|
||||
|
||||
## Generating a table
|
||||
|
||||
### Preview
|
||||
|
||||
```julia:table
|
||||
#hideall
|
||||
names = (:Taimur, :Catherine, :Maria, :Arvind, :Jose, :Minjie)
|
||||
numbers = (1525, 5134, 4214, 9019, 8918, 5757)
|
||||
println("@@simple-table")
|
||||
println("Name | Number")
|
||||
println(":--- | :---")
|
||||
println.("$name | $number" for (name, number) in zip(names, numbers))
|
||||
println("@@")
|
||||
raw"""
|
||||
~~~
|
||||
<style>
|
||||
.simple-table tr {
|
||||
padding:0;
|
||||
line-height:1em;
|
||||
}
|
||||
</style>
|
||||
~~~
|
||||
""" |> println
|
||||
```
|
||||
|
||||
\textoutput{table}
|
||||
|
||||
### Code
|
||||
|
||||
That can be obtained with:
|
||||
|
||||
`````plaintext
|
||||
```julia:table
|
||||
#hideall
|
||||
names = (:Taimur, :Catherine, :Maria, :Arvind, :Jose, :Minjie)
|
||||
numbers = (1525, 5134, 4214, 9019, 8918, 5757)
|
||||
println("Name | Number")
|
||||
println(":--- | :---")
|
||||
println.("$name | $number" for (name, number) in zip(names, numbers))
|
||||
```
|
||||
|
||||
\textoutput{table}
|
||||
`````
|
||||
|
||||
The code block will be executed and not shown (`#hideall`) generating a table line by line.
|
||||
In practice, the code generates the markdown
|
||||
|
||||
```markdown
|
||||
Name | Number
|
||||
:--- | :---
|
||||
Bob | 1525
|
||||
...
|
||||
Minjie | 5757
|
||||
```
|
||||
|
||||
which is captured and reprocessed by the `\textoutput` command.
|
||||
|
||||
This can be used effectively when combined with reading data files etc. and of course you could do further CSS styling of the table.
|
||||
|
||||
## Colourful circles
|
||||
|
||||
The trick can be used to generate SVG code too.
|
||||
|
||||
### Preview
|
||||
|
||||
\newcommand{\circle}[1]{~~~<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 4 4"><circle cx="2" cy="2" r="1.5" fill="#1"/></svg>~~~}
|
||||
|
||||
```julia:circles
|
||||
#hideall
|
||||
colors=(:pink, :lightpink, :hotpink, :deeppink, :mediumvioletred, :palevioletred, :coral, :tomato, :orangered, :darkorange, :orange, :gold, :yellow)
|
||||
print("@@ccols ")
|
||||
print.("\\circle{$c}" for c in colors)
|
||||
println("@@")
|
||||
```
|
||||
|
||||
\textoutput{circles}
|
||||
|
||||
### Code
|
||||
|
||||
That can obtained with (see detailed explanations further below)
|
||||
|
||||
```html
|
||||
\newcommand{\circle}[1]{
|
||||
~~~
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 4 4">
|
||||
<circle cx="2" cy="2" r="1.5" fill="#1"/></svg>
|
||||
~~~
|
||||
}
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
`````plaintext
|
||||
```julia:circles
|
||||
#hideall
|
||||
colors=(:pink, :lightpink, :hotpink, :deeppink,
|
||||
:mediumvioletred, :palevioletred, :coral,
|
||||
:tomato, :orangered, :darkorange, :orange,
|
||||
:gold, :yellow)
|
||||
print("@@ccols ")
|
||||
print.("\\circle{$c}" for c in colors)
|
||||
println("@@")
|
||||
```
|
||||
\textoutput{circles}
|
||||
`````
|
||||
|
||||
|
||||
The first part defines a command `\circle` which takes one argument for the fill colour and inserts SVG code for a circle with that colour.
|
||||
|
||||
The second part is a Julia code block which will be evaluated but not displayed on the page (since there is a `#hideall`).
|
||||
The code loops over the each colour `c` and prints `\circle{c}` so that the code block effectively generates:
|
||||
|
||||
```plaintext
|
||||
@@ccols \circle{pink}...\circle{yellow}@@
|
||||
```
|
||||
|
||||
this output is then captured and reprocessed with the `\textoutput{snippet}` command.
|
||||
|
||||
The last thing to do is to style the `colors` div appropriately:
|
||||
|
||||
```css
|
||||
.ccols {
|
||||
margin-top:1.5em;
|
||||
margin-bottom:1.5em;
|
||||
margin-left:auto;
|
||||
margin-right:auto;
|
||||
width: 60%;
|
||||
text-align: center;}
|
||||
.ccols svg {
|
||||
width:30px;}
|
||||
```
|
||||
|
||||
## Team cards
|
||||
|
||||
You may want to have a page with responsive team cards for instance where every card would follow the same layout but the content would be different.
|
||||
There are multiple ways you can do this with Franklin and a simple one below (adapted from [this tutorial](https://www.w3schools.com/howto/howto_css_team.asp)).
|
||||
The advantage of doing something like this is that it can help separate the content from the layout making both arguably easier more maintainable.
|
||||
|
||||
### Preview
|
||||
|
||||
\newcommand{\card}[5]{
|
||||
@@card
|
||||
![#1](/assets/img/team/!#2.jpg)
|
||||
@@container
|
||||
~~~
|
||||
<h2>#1</h2>
|
||||
~~~
|
||||
@@title #3 @@
|
||||
@@vitae #4 @@
|
||||
@@email #5 @@
|
||||
~~~
|
||||
<p><button class="button">Contact</button></p>
|
||||
~~~
|
||||
@@
|
||||
@@
|
||||
}
|
||||
|
||||
```julia:teamcards
|
||||
#hideall
|
||||
team = [
|
||||
(name="Jane Doe", pic="beth", title="CEO & Founder", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com"),
|
||||
(name="Mike Ross", pic="rick", title="Art Director", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com"),
|
||||
(name="John Doe", pic="meseeks", title="Designer", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com")
|
||||
]
|
||||
|
||||
"@@cards @@row" |> println
|
||||
for person in team
|
||||
"""
|
||||
@@column
|
||||
\\card{$(person.name)}{$(person.pic)}{$(person.title)}{$(person.vitae)}{$(person.email)}
|
||||
@@
|
||||
""" |> println
|
||||
end
|
||||
println("@@ @@") # end of cards + row
|
||||
|
||||
raw"""
|
||||
~~~
|
||||
<style>
|
||||
.column {
|
||||
float:left;
|
||||
width:30%;
|
||||
margin-bottom:16px;
|
||||
padding:0 8px;
|
||||
}
|
||||
@media (max-width:62rem) {
|
||||
.column {
|
||||
width:45%;
|
||||
display:block;
|
||||
}
|
||||
}
|
||||
@media (max-width:30rem){
|
||||
.column {
|
||||
width:95%;
|
||||
display:block;
|
||||
}
|
||||
}
|
||||
.card{
|
||||
box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2);
|
||||
}
|
||||
.card img {
|
||||
padding-left:0;
|
||||
width: 100%;
|
||||
}
|
||||
.container {
|
||||
padding: 0 16px;
|
||||
}
|
||||
.container::after, .row::after{
|
||||
content:"";
|
||||
clear:both;
|
||||
display:table;
|
||||
}
|
||||
.title {
|
||||
color:grey;
|
||||
}
|
||||
.vitae {
|
||||
margin-top:0.5em;
|
||||
}
|
||||
.email {
|
||||
font-family:courier;
|
||||
margin-top:0.5em;
|
||||
margin-bottom:0.5em;
|
||||
}
|
||||
.button{
|
||||
border:none;
|
||||
outline:0;
|
||||
display:inline-block;
|
||||
padding:8px;
|
||||
color:white;
|
||||
background-color:#000;
|
||||
text-align:center;
|
||||
cursor:pointer;
|
||||
width:100%;
|
||||
}
|
||||
.button:hover{
|
||||
background-color:#555;
|
||||
}
|
||||
</style>
|
||||
~~~
|
||||
""" |> println
|
||||
```
|
||||
|
||||
\textoutput{teamcards}
|
||||
|
||||
### Code
|
||||
|
||||
In order to do this you could first define a `\card` command:
|
||||
|
||||
```html
|
||||
\newcommand{\card}[5]{
|
||||
@@card
|
||||
![#1](/assets/img/team/!#2.jpg)
|
||||
@@container
|
||||
~~~
|
||||
<h2>#1</h2>
|
||||
~~~
|
||||
@@title #3 @@
|
||||
@@vitae #4 @@
|
||||
@@email #5 @@
|
||||
~~~
|
||||
<p><button class="button">Contact</button></p>
|
||||
~~~
|
||||
@@
|
||||
@@
|
||||
}
|
||||
```
|
||||
|
||||
And then use it in a loop that goes over each person:
|
||||
|
||||
`````plaintext
|
||||
```julia:teamcards
|
||||
#hideall
|
||||
team = [
|
||||
(name="Jane Doe", pic="beth", title="CEO & Founder", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com"),
|
||||
(name="Mike Ross", pic="rick", title="Art Director", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com"),
|
||||
(name="John Doe", pic="meseeks", title="Designer", vitae="Phasellus eget enim eu lectus faucibus vestibulum", email="example@example.com")
|
||||
]
|
||||
|
||||
"@@cards @@row" |> println
|
||||
for person in team
|
||||
"""
|
||||
@@column
|
||||
\\card{$(person.name)}{$(person.pic)}{$(person.title)}{$(person.vitae)}{$(person.email)}
|
||||
@@
|
||||
""" |> println
|
||||
end
|
||||
println("@@ @@") # end of cards + row
|
||||
```
|
||||
|
||||
\textoutput{teamcards}
|
||||
`````
|
||||
|
||||
That's about it! though of course a bit of CSS styling is needed such as:
|
||||
|
||||
```css
|
||||
.column {
|
||||
float:left;
|
||||
width:30%;
|
||||
margin-bottom:16px;
|
||||
padding:0 8px; }
|
||||
@media (max-width:62rem) {
|
||||
.column {
|
||||
width:45%;
|
||||
display:block; }
|
||||
}
|
||||
@media (max-width:30rem){
|
||||
.column {
|
||||
width:95%;
|
||||
display:block;}
|
||||
}
|
||||
.card { box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2); }
|
||||
.card img {
|
||||
padding-left:0;
|
||||
width: 100%; }
|
||||
.container { padding: 0 16px; }
|
||||
.container::after, .row::after{
|
||||
content: "";
|
||||
clear: both;
|
||||
display: table; }
|
||||
.title { color: grey; }
|
||||
.vitae { margin-top: 0.5em; }
|
||||
.email {
|
||||
font-family: courier;
|
||||
margin-top: 0.5em;
|
||||
margin-bottom: 0.5em; }
|
||||
.button{
|
||||
border: none;
|
||||
outline: 0;
|
||||
display: inline-block;
|
||||
padding: 8px;
|
||||
color: white;
|
||||
background-color: #000;
|
||||
text-align: center;
|
||||
cursor: pointer;
|
||||
width: 100%; }
|
||||
.button:hover{ background-color: #555; }
|
||||
```
|
||||
|
||||
## Python code blocks
|
||||
|
||||
Using [PyCall.jl](https://github.com/JuliaPy/PyCall.jl) you can evaluate Python code in Julia, and so you can do that in Franklin too.
|
||||
The code below could definitely be improved and generalised but the point here is to show how things can work together.
|
||||
You could adapt this to work with something like [RCall.jl](https://github.com/JuliaInterop/RCall.jl) as well.
|
||||
|
||||
\newcommand{\pycode}[2]{
|
||||
```julia:!#1
|
||||
#hideall
|
||||
using PyCall
|
||||
lines = replace("""!#2""", r"(^|\n)([^\n]+)\n?$" => s"\1res = \2")
|
||||
py"""
|
||||
$$lines
|
||||
"""
|
||||
println(py"res")
|
||||
```
|
||||
```python
|
||||
#2
|
||||
```
|
||||
\codeoutput{!#1}
|
||||
}
|
||||
|
||||
\pycode{py1}{
|
||||
import numpy as np
|
||||
np.random.seed(2)
|
||||
x = np.random.randn(5)
|
||||
r = np.linalg.norm(x) / len(x)
|
||||
np.round(r, 2)
|
||||
}
|
||||
|
||||
### Code
|
||||
|
||||
We first define a `\pycode` command that takes lines of python code, adds a `res = ` before the last line, runs the lines and finally show `res`.
|
||||
It also inputs the lines of code in a fenced block.
|
||||
|
||||
`````plaintext
|
||||
\newcommand{\pycode}[2]{
|
||||
```julia:!#1
|
||||
#hideall
|
||||
using PyCall
|
||||
lines = replace("""!#2""", r"(^|\n)([^\n]+)\n?$" => s"\1res = \2")
|
||||
py"""
|
||||
$$lines
|
||||
"""
|
||||
println(py"res")
|
||||
```
|
||||
```python
|
||||
#2
|
||||
```
|
||||
\codeoutput{!#1}
|
||||
}
|
||||
`````
|
||||
|
||||
calling the command is straightforward:
|
||||
|
||||
`````
|
||||
\pycode{py1}{
|
||||
import numpy as np
|
||||
np.random.seed(2)
|
||||
x = np.random.randn(5)
|
||||
r = np.linalg.norm(x) / len(x)
|
||||
np.round(r, 2)
|
||||
}
|
||||
`````
|
383
code/index.md
|
@ -1,383 +0,0 @@
|
|||
@def hascode = true
|
||||
|
||||
# Inserting and evaluating code
|
||||
|
||||
\blurb{Franklin makes it easy to insert code and the result of running the code; Julia code can be evaluated on the fly.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
## Overview
|
||||
|
||||
### Inserting code
|
||||
|
||||
As per Common Mark specifications, you have multiple ways of inserting code:
|
||||
|
||||
* **inline code**: you can use single backticks (\`) or double backticks (\`\`) (if the code contains single ticks) like so:
|
||||
|
||||
`````plaintext
|
||||
This is some `inline code` or ``inline ` code with a tick``.
|
||||
`````
|
||||
|
||||
* **code blocks**: it is recommended to use triple backticks (\`\`\`) optionally followed by a language name for highlighting like so:
|
||||
|
||||
`````
|
||||
This is some julia code:
|
||||
```julia
|
||||
a = 2
|
||||
@show a
|
||||
```
|
||||
`````
|
||||
|
||||
* **code blocks 2**: you can also use indented code blocks (lines starting with four spaces or a tab) but _fenced code blocks should be preferred_ and you now have to opt-in to use them by setting `@def indented_code = true`
|
||||
|
||||
`````
|
||||
This is some code:
|
||||
|
||||
a = 2
|
||||
@show a
|
||||
`````
|
||||
|
||||
**Note**: when either using indented code blocks or using fenced code blocks with no language name, then the code language for highlighting can be specified with the local page variable `lang` i.e. `@def lang = "julia"` (which is the default) or `@def lang = ""` if you don't want the code to be highlighted.
|
||||
|
||||
### Evaluating code
|
||||
|
||||
When presenting code in a post, it's often convenient to have a way to check the code works and the output shown corresponds to the code.
|
||||
In Franklin there are two approaches that help you for this:
|
||||
|
||||
@@tlist
|
||||
1. For Julia code, a **live-evaluation** of code blocks is supported,
|
||||
1. For all languages, you can run the script separately and use Franklin to insert the code file and/or the output generated by the code.
|
||||
@@
|
||||
|
||||
## Live evaluation (Julia)
|
||||
|
||||
Julia code blocks can be evaluated on the fly and their output either displayed as code or re-interpreted as Markdown.
|
||||
|
||||
\note{
|
||||
**Evaluation time**: when a code block is created or modified and the page is saved, it will trigger a page build that will _wait_ for the evaluation of the code block to complete. So if your code block takes a long time to execute, the page will not be updated before that's done.
|
||||
That being said, if you don't modify the code block, it will only be executed **once** as the output is saved to file.
|
||||
}
|
||||
|
||||
Code blocks that _should not_ be evaluated should be added as per standard markdown, so for instance:
|
||||
|
||||
`````
|
||||
```julia
|
||||
a = 10
|
||||
```
|
||||
`````
|
||||
|
||||
Code blocks that _should_ be evaluated should be added with `julia:path/to/script` where `path/to/script` indicates _where_ the script corresponding to the code block will be saved (**note**: the given path _must_ be in UNIX format even if you're on Windows)
|
||||
|
||||
`````
|
||||
```julia:./code/ex1
|
||||
a = 10
|
||||
@show a
|
||||
```
|
||||
`````
|
||||
|
||||
What this will do is:
|
||||
|
||||
@@tlist
|
||||
1. write the code to the file `/assets/[subpath]/code/ex1.jl`
|
||||
1. run the code and capture its output (`STDOUT`) and write it to `/assets/[subpath]/code/output/ex1.out`
|
||||
@@
|
||||
|
||||
The `[subpath]` here is the _exact same sub-path structure_ than to the page where the code block is inserted.
|
||||
To clarify, let's say you wrote the above code-block in
|
||||
|
||||
```
|
||||
/folder1/page1.md
|
||||
```
|
||||
|
||||
then with the syntax above, the script will be saved in
|
||||
|
||||
```
|
||||
/__site/assets/folder1/code/ex1.jl
|
||||
```
|
||||
|
||||
### More on paths
|
||||
|
||||
There are three ways you can specify where the script corresponding to a code-block should be saved.
|
||||
|
||||
@@tlist
|
||||
1. _relative to the page_: `./[p]/script` is as above, it will write the code block to `/assets/[subpath]/p/script.jl` where `subpath` corresponds to the sub-path of the page where the code block is inserted (path below `/src/`)
|
||||
1. _relative to the assets dir_: `p/script` will write the code block to `/assets/p/script.jl`
|
||||
1. _full path_: `/p/script` will write the code block to `/p/script.jl`
|
||||
@@
|
||||
|
||||
**Note**: when code blocks are evaluated, their output (`STDOUT`) is captured and saved at `[path]/output/script.out` where `[path]` is what precedes `script.jl` in the cases above.
|
||||
|
||||
### Inserting the output
|
||||
|
||||
Let's say you've added the following code block:
|
||||
|
||||
`````
|
||||
```julia:./code_pg1/ex1
|
||||
using LinearAlgebra
|
||||
a = [1, 2, 3]
|
||||
@show dot(a, a)
|
||||
```
|
||||
`````
|
||||
|
||||
In order to show the raw output (whatever was captured in STDOUT) as a code block, write
|
||||
|
||||
```
|
||||
\output{./code_pg1/ex1}
|
||||
```
|
||||
|
||||
which in the present example will introduce exactly the following HTML
|
||||
|
||||
```html
|
||||
<pre><code class="language-julia">dot(a, a) = 14</code></pre>
|
||||
```
|
||||
|
||||
and will look like
|
||||
|
||||
```
|
||||
dot(a, a) = 14
|
||||
```
|
||||
|
||||
If you now change the vector `a` in the code block, the page will be re-compiled with the code-block re-evaluated and the new output will be shown.
|
||||
|
||||
If you would like the output to be re-interpeted by Franklin as text, you can use `\textoutput` instead.
|
||||
Here's an example:
|
||||
|
||||
`````
|
||||
```julia:./code_pg1/ex2
|
||||
using Statistics
|
||||
temps = (15, 15, 14, 16, 18, 19, 20, 12, 10, 24)
|
||||
println("The _average_ temperature is **$(mean(temps))°C**.")
|
||||
```
|
||||
\textoutput{./code_pg1/ex2}
|
||||
`````
|
||||
|
||||
That code block and the `\textoutput` command will appear as:
|
||||
|
||||
```julia
|
||||
using Statistics
|
||||
temps = (15, 15, 14, 16, 18, 19, 20, 12, 10, 24)
|
||||
println("The _average_ temperature is **$(mean(temps))°C**.")
|
||||
```
|
||||
|
||||
The _average_ temperature is **16.3°C**.
|
||||
|
||||
Finally if you want to show your code "notebook-style", i.e. both STDOUT and the result of the last line, use `\show`:
|
||||
|
||||
`````
|
||||
```julia:ex_show
|
||||
x = 5
|
||||
println("hello")
|
||||
x^2
|
||||
```
|
||||
\show{ex_show}
|
||||
`````
|
||||
|
||||
resulting in:
|
||||
|
||||
```julia:ex_show
|
||||
x = 5
|
||||
println("hello")
|
||||
x^2
|
||||
```
|
||||
\show{ex_show}
|
||||
|
||||
|
||||
### Hiding lines
|
||||
|
||||
Sometimes you may want to run some lines but hide them from the presentation, for this just use `# hide` at the end of the line (`hide` is not case sensitive so `# HiDe` would be fine too):
|
||||
|
||||
`````
|
||||
```julia:./code_pg1/ex1
|
||||
using LinearAlgebra # hide
|
||||
a = [1, 2, 3]
|
||||
@show dot(a, a)
|
||||
```
|
||||
`````
|
||||
|
||||
You could also hide the entire code block if you only care about the output, for this put a `# hideall` on any line:
|
||||
|
||||
`````
|
||||
```julia:./code_pg1/ex2
|
||||
#hideall
|
||||
using Statistics
|
||||
temps = (15, 15, 14, 16, 18, 19, 20, 12, 10, 24)
|
||||
println("The _average_ temperature is **$(mean(temps))°C**.")
|
||||
```
|
||||
\textoutput{./code_pg1/ex2}
|
||||
`````
|
||||
|
||||
Which will appear as just:
|
||||
|
||||
The _average_ temperature is **16.3°C**.
|
||||
|
||||
### Project.toml
|
||||
|
||||
It can be convenient to set up your website as you would a Julia environment: _activating_ it and _adding_ the packages that you will use in code blocks.
|
||||
In order to do this, just activate the environment as you would otherwise, this will generate a `Project.toml` which will subsequently be used by Franklin without you having to worry about it.
|
||||
|
||||
For instance, let's say that you want to use `PyCall` in some code blocks, then before starting the Franklin server do
|
||||
|
||||
```julia-repl
|
||||
(1.x) pkg> activate .
|
||||
(myWebsite) pkg> add PyCall
|
||||
```
|
||||
|
||||
once that's done, if you now start the server, Franklin will write
|
||||
|
||||
```julia-repl
|
||||
julia> serve()
|
||||
Activating environment at `~/Desktop/myWebsite/Project.toml`
|
||||
```
|
||||
|
||||
In other words, whenever you start the server, Franklin will now activate the environment with that `Project.toml`.
|
||||
This is particularly useful if you intend to write a tutorial website (for a live example of this, see the [MLJ Tutorials](https://alan-turing-institute.github.io/MLJTutorials/)).
|
||||
|
||||
### Plots
|
||||
|
||||
Using the machinery introduced above, you can also evaluate code that generates a plot which you can then include on the page.
|
||||
In the example below, `PyPlot` is used but you could do something similar with other frameworks.
|
||||
|
||||
Assuming you've added `PyPlot` to your environment, this markdown
|
||||
|
||||
`````markdown
|
||||
```julia:pyplot1
|
||||
using PyPlot
|
||||
figure(figsize=(8, 6))
|
||||
x = range(-2, 2, length=500)
|
||||
for α in 1:5
|
||||
plot(x, sinc.(α .* x))
|
||||
end
|
||||
savefig(joinpath(@OUTPUT, "sinc.svg")) # hide
|
||||
```
|
||||
|
||||
\fig{sinc}
|
||||
`````
|
||||
|
||||
will give:
|
||||
|
||||
```julia:pyplot1
|
||||
using PyPlot
|
||||
figure(figsize=(8, 6))
|
||||
x = range(-2, 2, length=500)
|
||||
for α in 1:5
|
||||
plot(x, sinc.(α .* x))
|
||||
end
|
||||
savefig(joinpath(@OUTPUT, "sinc.svg")) # hide
|
||||
```
|
||||
|
||||
\fig{sinc}
|
||||
|
||||
**Note**: observe that here everything is done with relative paths, `pyplot1` is placed in the `/assets/` folder relatively to the path of the current page and the `\fig` since it's given a path that doesn't start with `/` or `./` will also look in that folder to try to find a figure which starts with the name `sinc`. See also [more about paths](#more_on_paths).
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
A few things can go wrong when attempting to use and evaluate code blocks.
|
||||
The first thing to do if no output is shown or an error appears is to make sure that:
|
||||
|
||||
@@tlist
|
||||
1. if the code uses packages, these packages are available in the local environment,
|
||||
1. the code "just works" in the REPL.
|
||||
@@
|
||||
|
||||
If this is the case and you still have issues, then you may want to force re-evaluation of the code on the page.
|
||||
In such a case, try adding `@def reeval = true` on the page which will cause **all** code blocks on the page to be completely re-evaluated and their output re-generated.
|
||||
Assuming that helped, you will then want to remove that line as otherwise that page will be fully re-evaluated _every single time the page is modified_ which will cause an unnecessary overhead.
|
||||
|
||||
**Important note**: unless you explicitly use `@def reeval = true`, code blocks are evaluated *only* if:
|
||||
@@tlist
|
||||
- an earlier code block has been evaluated (in which case, since their results may depend on it, all subsequent blocks are re-evaluated),
|
||||
- the content of the code block has changed.
|
||||
@@
|
||||
An example where this can be a bit tricky is if your code block calls a function on a file, for instance `read(file, String)`; if the underlying *file* is changed, the code block will **not** be re-evaluated (since the code doesn't change), so in such cases you will want to use a `@def reeval = true`.
|
||||
|
||||
## Offline evaluation (any language)
|
||||
|
||||
The philosophy here is:
|
||||
|
||||
@@tlist
|
||||
* keep your code snippets in appropriate subfolders of `/assets/` where they can be run and their output can be saved, this can be compared to a `test/` folder in a Julia package,
|
||||
* run some or all of the snippets (before running Franklin),
|
||||
* use `\input{...}{...}` in your markdown (see below) and when the website is updated, it will plug-in the most recent parts that have been generated.
|
||||
@@
|
||||
|
||||
That way, if you modify the code, everything will be updated on the website too while ensuring that the code actually runs and generates the output you're displaying.
|
||||
|
||||
Again, the script files can contain `# hide` at the end of lines you do not want to show (`#` to be replaced by whatever symbol indicates comments in that language).
|
||||
|
||||
The `generate_results.jl` file should run the scripts and redirect outputs to the `assets/[path]/output` directory.
|
||||
You can use something like the script below (if you generate an example website with `newsite`, it's already in there) though you can of course modify it as you wish.
|
||||
|
||||
```julia
|
||||
dir = @__DIR__
|
||||
"""
|
||||
genplain(s)
|
||||
|
||||
Small helper function to run some code and redirect the output (stdout) to a file.
|
||||
"""
|
||||
function genplain(s::String)
|
||||
open(joinpath(dir, "output", "$(splitext(s)[1]).out"), "w") do outf
|
||||
redirect_stdout(outf) do
|
||||
include(joinpath(dir, s))
|
||||
end
|
||||
end
|
||||
end
|
||||
# run `script1.jl` and redirect what it prints to `output/script1.out`
|
||||
genplain("script1.jl")
|
||||
# run `script2.jl` which has a savefig(joinpath(@__DIR__, "output", "script2.png"))
|
||||
include("script2.jl")
|
||||
```
|
||||
|
||||
The function `genplain("scriptname.jl")` just redirects the output of the script to `output/scriptname.out`.
|
||||
So for instance if you have in `assets/scripts/script1.jl`
|
||||
|
||||
```julia
|
||||
print("hello")
|
||||
```
|
||||
|
||||
Then `genplain("script1.jl")` will generate `/assets/scripts/output/script1.out` with content
|
||||
|
||||
```julia
|
||||
hello
|
||||
```
|
||||
|
||||
\note{You could have scripts in any language here (`R`, `Python`, ...) as long as the folder structure is the same.}
|
||||
|
||||
### Inserting code
|
||||
|
||||
In order to insert the code of a script and have it highlighted you can use
|
||||
|
||||
```
|
||||
\input{julia}{scripts/script1.jl}
|
||||
```
|
||||
|
||||
This will insert the content of the file `/assets/scripts/script1.jl` (see also the section earlier on paths) into a block that will be highlighted as julia code.
|
||||
|
||||
### Plain-text output
|
||||
|
||||
In order to insert the plain-text output of a script, you can use
|
||||
|
||||
```
|
||||
\output{scripts/script1.jl}
|
||||
```
|
||||
|
||||
This will insert the content of the file `/assets/scripts/script1.out` into a non-highlighted code-block.
|
||||
|
||||
### Plot output
|
||||
|
||||
In order to insert a plot generated by a script, you can use `\fig` as indicated earlier or
|
||||
|
||||
```
|
||||
\input{plot}{scripts/script1.jl}
|
||||
```
|
||||
|
||||
or `\input{plot:id}{scripts/script1.jl}`. This will look for an image file with root name `/assets/scripts/script1.ext` where `ext` is `gif, png, jp(e)g, svg`.
|
||||
If you use `plot:id` then it will look for an image file with root name `/assets/scripts/script1id.ext`.
|
||||
|
||||
The `plot:id` option is useful if you have a script that generates several plots for instance.
|
||||
|
||||
### Slicing up
|
||||
|
||||
The structure in the `generate_results.jl` effectively means that all your code is run as one big script.
|
||||
This also means that if you want to slice some of your code in several parts and show intermediate outputs (e.g. plots), you can just do that by having a `script_1_p1.jl`, `script_1_p2.jl` etc. and then just use `\input` multiple times.
|
104
code/literate.md
|
@ -1,104 +0,0 @@
|
|||
@def hascode = true
|
||||
@def showall = true
|
||||
@def hasmath = true
|
||||
|
||||
# Work with Literate.jl
|
||||
|
||||
\blurb{Franklin works seamlessly with Literate to offer a convenient way to write and maintain tutorials.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
## Overview
|
||||
|
||||
[Literate.jl](https://github.com/fredrikekre/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:
|
||||
|
||||
@@tlist
|
||||
* 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](https://alan-turing-institute.github.io/MLJTutorials/)).
|
||||
|
||||
### 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:
|
||||
|
||||
@@tlist
|
||||
* _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:
|
||||
|
||||
```julia:ee0
|
||||
x = randn(10)
|
||||
x[1:3]
|
||||
```
|
||||
|
||||
to just
|
||||
|
||||
```julia:ee1
|
||||
x = randn(10)
|
||||
```
|
||||
|
||||
You can also use `@show` or `println` to show specific things beyond the last line
|
||||
|
||||
```julia:ee2
|
||||
x = rand(10)
|
||||
println(sum(x))
|
||||
y = 5
|
||||
```
|
||||
|
||||
if the last line is a `@show` or `print` then only that is shown:
|
||||
|
||||
```julia:ee3
|
||||
x = randn(10)
|
||||
@show x[1]
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
### Script
|
||||
|
||||
`````julia
|
||||
# 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
|
||||
|
||||
\literate{/_literate/script_ee.jl} <!--_-->
|
|
@ -1,16 +0,0 @@
|
|||
# Extras
|
||||
|
||||
In this section of the manual, the assumption is that you already have a fairly good idea of how Franklin works so that basic explanations are skipped (refer to the rest of the manual for help).
|
||||
|
||||
The aim is to show how Franklin can work with other useful libraries to add functionalities to your website.
|
||||
|
||||
As usual, these examples are just meant to show what can be done, not the best way to do it, feel free to modify the examples at will!
|
||||
Also, if you come up with other nice ways of extending Franklin, don't hesitate to make a suggestion for an example to be added here.
|
||||
|
||||
## List of examples
|
||||
|
||||
@@flist
|
||||
* \goto{/extras/lunr/} Add a search functionality to your website using [`lunr.js`](https://lunrjs.com/),
|
||||
* \goto{/extras/literate/} Generate auxiliary files with Literate.
|
||||
* \goto{/extras/plotly/} Add interactive plots with [Plotly](https://plot.ly/javascript/).
|
||||
@@
|
|
@ -1,100 +0,0 @@
|
|||
@def hascode = true
|
||||
|
||||
# Generating auxiliary files with Literate
|
||||
|
||||
See also [how to interact with literate scripts](/code/literate/).
|
||||
|
||||
[Literate.jl](https://github.com/fredrikekre/Literate.jl) allows to pre and post-process a script in order, for instance, to generate a notebook out of a script.
|
||||
This can be convenient if you want to have a tutorial be downloadable as a standalone notebook or as a scrubbed script.
|
||||
|
||||
This page presents one way of doing this which is used in [MLJTutorials](https://github.com/alan-turing-institute/MLJTutorials) and which might inspire your own approach.
|
||||
|
||||
The key ingredients are:
|
||||
|
||||
@@tlist
|
||||
1. use Literate to generate derived files,
|
||||
1. use `gh-pages` to push the generated file to GitHub,
|
||||
1. add this as a `final` hook to `publish`.
|
||||
@@
|
||||
|
||||
In what follows, it is assumed you have your Literate scripts in a folder `/scripts/` and that you're using GitHub.
|
||||
It shouldn't be hard to modify that to suit your own case.
|
||||
|
||||
|
||||
## Using Literate to generate auxiliary files
|
||||
|
||||
Literate can manipulate scripts fairly easily, for instance to generate notebooks:
|
||||
|
||||
```julia
|
||||
scripts = joinpath.("scripts", readdir("scripts"))
|
||||
nbpath = joinpath("generated", "notebooks")
|
||||
isdir(nbpath) || mkpath(nbpath)
|
||||
|
||||
for script in scripts
|
||||
# Generate annotated notebooks
|
||||
Literate.notebook(script, nbpath,
|
||||
execute=false, documenter=false)
|
||||
end
|
||||
```
|
||||
|
||||
This will go over all scripts in `/scripts/` and call `Literate.notebook` to generate a derived notebook in a `/generated/` folder (which you will want to add to your `.gitignore`).
|
||||
|
||||
## Push the generated files to a page branch
|
||||
|
||||
Start by installing `gh-pages` with `npm`:
|
||||
|
||||
```bash
|
||||
$> npm install gh-pages
|
||||
```
|
||||
|
||||
Using the package [NodeJS.jl](https://github.com/davidanthoff/NodeJS.jl) it is then easy to use `gh-pages` to push the generated notebooks to a folder on the `gh-pages` branch:
|
||||
|
||||
```julia
|
||||
using NodeJS
|
||||
|
||||
JS_GHP = """
|
||||
var ghpages = require('gh-pages');
|
||||
ghpages.publish('generated/', function(err) {});
|
||||
"""
|
||||
|
||||
run(`$(nodejs_cmd()) -e $JS_GHP`)
|
||||
```
|
||||
|
||||
Now these generated files are available on that branch without polluting your `master` branch.
|
||||
You can see this live on the [MLJTutorials repo](https://github.com/alan-turing-institute/MLJTutorials/tree/gh-pages).
|
||||
|
||||
You can link to these generated notebooks with links adapted from:
|
||||
|
||||
```plaintext
|
||||
https://raw.githubusercontent.com/username/project/gh-pages/notebooks/theNotebook.ipynb
|
||||
```
|
||||
|
||||
See [this page](https://alan-turing-institute.github.io/MLJTutorials/pub/isl/lab-2.html) for example.
|
||||
|
||||
## Add the whole process to `publish`
|
||||
|
||||
You may want to re-generate all notebooks prior to pushing updates to GitHub.
|
||||
For this, use the `final` keyword of `publish` to which you can pass a function to use before publishing updates.
|
||||
For instance:
|
||||
|
||||
```julia
|
||||
function gen_literate()
|
||||
scripts = joinpath.("scripts", readdir("scripts"))
|
||||
nbpath = joinpath("generated", "notebooks")
|
||||
isdir(nbpath) || mkpath(nbpath)
|
||||
|
||||
for script in scripts
|
||||
# Generate annotated notebooks
|
||||
Literate.notebook(script, nbpath,
|
||||
execute=false, documenter=false)
|
||||
end
|
||||
JS_GHP = """
|
||||
var ghpages = require('gh-pages');
|
||||
ghpages.publish('generated/', function(err) {});
|
||||
"""
|
||||
run(`$(nodejs_cmd()) -e $JS_GHP`)
|
||||
end
|
||||
# ... serve etc ...
|
||||
# ... then finally ...
|
||||
publish(final=gen_literate)
|
||||
```
|
143
extras/lunr.md
|
@ -1,143 +0,0 @@
|
|||
@def hascode = true
|
||||
|
||||
# Add search with Lunr
|
||||
|
||||
\toc\skipline
|
||||
|
||||
[`lunr.js`](https://lunrjs.com/) is a neat little Javascript library that allows to equip your website with a search functionality fairly easily.
|
||||
|
||||
The steps below show a simple way of doing this matching what is done on this website.
|
||||
Once it's working, you might want to adjust the `build_index.js` and/or the `lunrclient.js` to match your needs.
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
### Libraries
|
||||
|
||||
Install `lunr` and `cheerio` (a HTML parser) with `node`:
|
||||
|
||||
```bash
|
||||
$> npm install lunr
|
||||
$> npm install cheerio
|
||||
```
|
||||
|
||||
(you might have to add `sudo` before `npm`).
|
||||
|
||||
### Files
|
||||
|
||||
Copy [this folder](https://github.com/tlienart/franklindocs/tree/master/_libs/lunr) to a `/_libs/lunr/` directory.
|
||||
Discard the `lunr_index.js` which is the index of this website, you will rebuild your own of course!
|
||||
|
||||
The important files are `build_index.js` and `lunrclient.js` (of which a minified version is provided which you will want to re-generate if you modify the base file).
|
||||
These files are adapted from [this repository](https://github.com/BLE-LTER/Lunr-Index-and-Search-for-Static-Sites) which shows how to use Lunr on a static website.
|
||||
|
||||
You can choose whether to serve your own copy of `lunr.min.js` (done here) or to use an online version via
|
||||
|
||||
```html
|
||||
<script src="https://unpkg.com/lunr/lunr.js"></script>
|
||||
```
|
||||
|
||||
|
||||
### Index builder
|
||||
|
||||
The file `build_index.js` does the following:
|
||||
|
||||
@@tlist
|
||||
- it goes over all files in a `HTML_FOLDER` (by default: `/__site/`),
|
||||
- it builds an index `lunr_index.js` which can subsequently be queried upon the user entering search terms.
|
||||
@@
|
||||
|
||||
By default, the index built is fairly barebone to reduce the size of the generated index. If you want fancier search, you might want to modify this a bit to add a preview of the page, boost results depending on where there are (title, keyword, ...), add stop words, etc. (Refer to the [Lunr docs](https://lunrjs.com/docs/index.html) for this as well as [the example repo](https://github.com/BLE-LTER/Lunr-Index-and-Search-for-Static-Sites) mentioned earlier or [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl/blob/master/assets/html/search.js)'s version).
|
||||
|
||||
\note{
|
||||
Modify this file at will but be careful with the lines with `PATH_PREPEND` if your website is a project website (i.e. the root URL is something like `username.github.io/project/`). These lines help ensure that the generated links are valid. See also the section on [updating the index](#buildingupdating_the_index).
|
||||
}
|
||||
|
||||
### Client
|
||||
|
||||
The file `lunrclient.js` (and its minified version) does the following:
|
||||
|
||||
@@tlist
|
||||
- query the index
|
||||
- display the results
|
||||
@@
|
||||
|
||||
You might want to modify the `parseLunrResults` if you want the results to be displayed differently.
|
||||
|
||||
\note{
|
||||
If you modify this file, make sure it's called properly in the `src/_html_parts/index.html` and, eventually, [minify it](https://jscompress.com/).
|
||||
}
|
||||
|
||||
## Adding a search box
|
||||
|
||||
### Adding a form in `head.html`
|
||||
|
||||
The search box on this website is added with the following HTML in `_layout/head.html`:
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<!-- first few lines ... -->
|
||||
<script src="/libs/lunr/lunr.min.js"></script>
|
||||
<script src="/libs/lunr/lunr_index.js"></script>
|
||||
<script src="/libs/lunr/lunrclient.min.js"></script>
|
||||
</head>
|
||||
<!-- ... -->
|
||||
<form id="lunrSearchForm" name="lunrSearchForm">
|
||||
<input class="search-input" name="q" placeholder="Enter search term" type="text">
|
||||
<input type="submit" value="Search" formaction="/search/index.html">
|
||||
</form>
|
||||
<-- ... -->
|
||||
```
|
||||
|
||||
You may want to style it a bit like so:
|
||||
|
||||
```css
|
||||
.result-title a { text-decoration: none; }
|
||||
.result-title a:hover { text-decoration: underline; }
|
||||
.result-preview { color: #808080; }
|
||||
.resultCount { color: #808080; }
|
||||
.result-query { font-weight: bold; }
|
||||
#lunrSearchForm { margin-top: 1em; }
|
||||
```
|
||||
|
||||
### Target search page
|
||||
|
||||
You also need to add a `src/search.md` to display the results with the appropriate divs:
|
||||
|
||||
```html
|
||||
@def title = "Search ⋅ YourWebsite"
|
||||
|
||||
## Search
|
||||
|
||||
Number of results found: ~~~<span id="resultCount"></span>~~~
|
||||
|
||||
~~~
|
||||
<div id="searchResults"></div>
|
||||
~~~
|
||||
```
|
||||
|
||||
Note that if you modify the `id` of these elements, you will need to adapt the `lunrclient` file(s) accordingly.
|
||||
|
||||
## Building/updating the index
|
||||
|
||||
Franklin exports a `lunr()` function which
|
||||
|
||||
@@tlist
|
||||
- checks that you have the right files at the right place,
|
||||
- (re)builds the index, prepending a path to links if required.
|
||||
@@
|
||||
|
||||
If you are experimenting locally, just call `lunr()` then `serve()` and test that searching works as expected.
|
||||
|
||||
When you are ready to update your website you can either:
|
||||
|
||||
@@tlist
|
||||
1. (recommended) Call `publish(final=lunr)`,
|
||||
1. Call `lunr()` or `lunr(prepath)` if there is a prepath and then publish your updates manually.
|
||||
@@
|
||||
|
||||
The `publish(final=lunr)` calls the `lunr` function as a last step prior to doing a `git push`.
|
||||
An advantage of using this is that Franklin will properly handle the `prepath` if there is one defined in your `config.md`.
|
||||
|
||||
\note{
|
||||
This `final=` keyword can be used with your own functions `()->nothing` if you need to do some post-processing with the generated files before pushing.
|
||||
}
|
113
extras/plotly.md
|
@ -1,113 +0,0 @@
|
|||
@def hascode = true
|
||||
@def hasplotly = true
|
||||
|
||||
# Work with Plotly
|
||||
|
||||
If you want interactive plots on some pages and are not afraid of using heavy javascript libraries, then [Plotly](https://plot.ly/javascript/) is a nice library.
|
||||
The Julia wrapper [PlotlyJS.jl](https://github.com/sglyon/PlotlyJS.jl) can be used to generate Plotly plots.
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
Download [`plotly.min.js`](https://cdn.plot.ly/plotly-latest.min.js) saving it to `/_libs/plotly/plotly.min.js`.
|
||||
|
||||
Then create a variable `hasplotly` with default value `false`: in your `config.md` write
|
||||
|
||||
```
|
||||
@def hasplotly = false
|
||||
```
|
||||
|
||||
Finally, in your `src/_layout/head.html` add
|
||||
|
||||
```html
|
||||
{{if hasplotly}} <script src="/libs/plotly/plotly.min.js"></script> {{end}}
|
||||
```
|
||||
|
||||
## Offline-generated plot
|
||||
|
||||
Assuming you already have the Plotly code for some plot, displaying the result on a page with Franklin is now pretty straightforward.
|
||||
Start by adding
|
||||
|
||||
```
|
||||
@def hasplotly = true
|
||||
```
|
||||
|
||||
so that the JS library will be loaded then somewhere appropriate add:
|
||||
|
||||
```html
|
||||
~~~
|
||||
<div id="tester" style="width:600px;height:350px;"></div>
|
||||
|
||||
<script>
|
||||
TESTER = document.getElementById('tester');
|
||||
Plotly.plot( TESTER, [{
|
||||
x: [1, 2, 3, 4, 5],
|
||||
y: [1, 2, 4, 8, 16] }], {
|
||||
margin: { t: 0 } } );
|
||||
</script>
|
||||
~~~
|
||||
```
|
||||
|
||||
This will give:
|
||||
|
||||
~~~
|
||||
<div id="tester" style="width:600px;height:350px;"></div>
|
||||
|
||||
<script>
|
||||
TESTER = document.getElementById('tester');
|
||||
Plotly.plot( TESTER, [{
|
||||
x: [1, 2, 3, 4, 5],
|
||||
y: [1, 2, 4, 8, 16] }], {
|
||||
margin: { t: 0 } } );
|
||||
</script>
|
||||
~~~
|
||||
|
||||
## Live-generated plot
|
||||
|
||||
One step further is to use `PlotlyJS` to define a plot then pass the result to Franklin.
|
||||
Start by adding `PlotlyJS` and `Random` to your environment:
|
||||
|
||||
```julia-repl
|
||||
(myWebsite) pkg> add PlotlyJS Random
|
||||
```
|
||||
|
||||
Then, beyond the `@def hasplotly = true`, add the following code:
|
||||
|
||||
`````plaintext
|
||||
```julia:ex1
|
||||
using PlotlyJS
|
||||
z = [10 10.625 12.5 15.625 20
|
||||
5.625 6.25 8.125 11.25 15.625
|
||||
2.5 3.125 5. 8.125 12.5
|
||||
0.625 1.25 3.125 6.25 10.625
|
||||
0 0.625 2.5 5.625 10]
|
||||
|
||||
data = contour(; z=z)
|
||||
layout = Layout(; title="Basic Contour Plot")
|
||||
plt = plot(data, layout)
|
||||
|
||||
fdplotly(json(plt)) # hide
|
||||
```
|
||||
\textoutput{ex1}
|
||||
`````
|
||||
|
||||
**Note**: the `fdplotly` is a convenience function exported by `Franklin`; it just prints the required HTML such that a plotly object gets placed. It takes the JSON string of the plot (which you can get with `json(plt)`) and takes two optional keyword arguments:
|
||||
- `id`: to specify the name of the div the plotly object is associated to, it's randomly generated by default, and,
|
||||
- `style` which takes a string indicating the desired CSS for the div e.g. the default is `"width:600px;height:350px"`.
|
||||
|
||||
The code block above gives:
|
||||
|
||||
```julia:ex1
|
||||
using PlotlyJS
|
||||
z = [10 10.625 12.5 15.625 20
|
||||
5.625 6.25 8.125 11.25 15.625
|
||||
2.5 3.125 5. 8.125 12.5
|
||||
0.625 1.25 3.125 6.25 10.625
|
||||
0 0.625 2.5 5.625 10]
|
||||
|
||||
data = contour(; z=z)
|
||||
layout = Layout(; title="Basic Contour Plot")
|
||||
plt = plot(data, layout)
|
||||
|
||||
fdplotly(json(plt)) # hide
|
||||
```
|
||||
\textoutput{ex1}
|
4
index.md
|
@ -28,6 +28,10 @@ function len(p::T) where T<:Point
|
|||
end
|
||||
```
|
||||
|
||||
## A bit about myself
|
||||
|
||||
My interest in science started from a very early age I was in love with physics because a teacher in elementary school had a copy of the book `COSMOS` which he lend me and I was marveled by the words of [Carl Sagan](https://en.wikipedia.org/wiki/Carl_Sagan)
|
||||
|
||||
<!--
|
||||
# Building static websites in Julia
|
||||
|
||||
|
|
|
@ -1,66 +0,0 @@
|
|||
<!--
|
||||
reviewed: 22/12/19
|
||||
-->
|
||||
|
||||
@def hascode = true
|
||||
|
||||
# Classes
|
||||
|
||||
\blurb{Use Franklin's classes or add your own.}
|
||||
|
||||
\lineskip
|
||||
|
||||
By now you know that you can add `@@divname ... @@` anywhere you want in your content in order to define an environment and style it.
|
||||
Below we detail the default classes as well as some tricks that can be useful to style your content.
|
||||
|
||||
## Franklin's classes
|
||||
|
||||
@@lalignb
|
||||
| Name | Function |
|
||||
| ------ | ---- |
|
||||
| `franklin-content` | wraps around the content of a page, so when a `mypage.md` is converted to some html, it gets inserted in the scaffolding as `<div class="franklin-content"> some html </div>` (\*)
|
||||
| `franklin-toc` | wraps around the inserted table of contents
|
||||
| `fnref` | wraps around a footnote reference
|
||||
| `fndef` | wraps around footnote definitions
|
||||
| `fndef-content` | wraps around the content of footnote definitions
|
||||
| `fndef-backref` | wraps around the back-reference of a footnote definition
|
||||
@@
|
||||
|
||||
**Notes**:\\
|
||||
\smindent{(\*)} \smnote{you can change this name setting the global page variable `div_content` in your `config.md`}.\\
|
||||
|
||||
## Simple tricks
|
||||
|
||||
As soon as you're using a style more than once, it makes sense to create it as a command.
|
||||
This makes it much easier to maintain and re-use.
|
||||
For instance, consider the following simple examples:
|
||||
|
||||
```html
|
||||
\newcommand{\blurb}[1]{
|
||||
~~~
|
||||
<span style="font-size:24px;font-weight:300;">!#1</span>
|
||||
~~~
|
||||
}
|
||||
```
|
||||
|
||||
```html
|
||||
\newcommand{\note}[1]{@@note @@title ⚠ Note@@ @@content #1 @@ @@}
|
||||
```
|
||||
|
||||
Further, you can pass the style as an argument:
|
||||
|
||||
\newcommand{\spstyle}[2]{~~~<span style="#1">#2</span>~~~}
|
||||
|
||||
```html
|
||||
\newcommand{\spstyle}[2]{~~~<span style="#1">#2</span>~~~}
|
||||
```
|
||||
|
||||
and for instance:
|
||||
|
||||
```plaintext
|
||||
\spstyle{font-variant:small-caps;font-size:15px;color:cornflowerblue}{formatted text}
|
||||
```
|
||||
|
||||
gives you: \spstyle{font-variant:small-caps;font-size:15px;color:cornflowerblue}{formatted text}.
|
||||
|
||||
In fact, that one is pre-defined in Franklin, `\style{style}{text}` does precisely that.
|
|
@ -1,247 +0,0 @@
|
|||
@def hascode = true
|
||||
|
||||
<!--
|
||||
reviewed: 22/12/19
|
||||
-->
|
||||
|
||||
# Templates
|
||||
|
||||
\blurb{Start from one of the template or build your own.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
\lineskip
|
||||
|
||||
The pre-defined templates that are currently available in Franklin with the `newsite` function can be viewed ~~~<a href="https://tlienart.github.io/FranklinTemplates.jl/" target="_blank" rel="noopener noreferrer">here</a>~~~ (_opens in a new tab_).
|
||||
|
||||
## Adapting a theme to Franklin
|
||||
|
||||
\note{If you end up doing this, please consider making a PR to [FranklinTemplates](https://github.com/tlienart/FranklinTemplates.jl)!}
|
||||
|
||||
On this page, I'll take [Jemdoc's website layout](http://jemdoc.jaboc.net/) and show how it can be adapted to be a working Franklin template.
|
||||
This will hopefully also show you how to adapt / modify an existing template.
|
||||
|
||||
Jemdoc's layout looks like this:
|
||||
|
||||
![](/assets/jemdoc/jemdoc1.png)
|
||||
|
||||
### Getting started
|
||||
|
||||
In order to get a blueprint for the folder etc, let's first create a Franklin site with the `basic` template:
|
||||
|
||||
```julia-repl
|
||||
julia> newsite("jemdoc", template="basic")
|
||||
```
|
||||
|
||||
You can serve the site in order to see the modifications directly in your browser which can be useful to fine tune the port of the layout.
|
||||
|
||||
We will need to provide the appropriate stylesheet in `_css/` and adjust the layout part in `_layout/`.
|
||||
|
||||
### Adapting the head and foot
|
||||
|
||||
The file `_html_parts/head.html` is the most important one you will have to adjust.
|
||||
|
||||
Let us first change the name of the main stylesheet `_css/basic.css` to `_css/jemdoc.css` which is more appropriate.
|
||||
The reference to the stylesheet in `head.html` consequently has to be changed to mention `jemdoc.css` instead of `basic.css`:
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="/css/jemdoc.css">
|
||||
```
|
||||
|
||||
The following step is fairly simple:
|
||||
|
||||
@@tlist
|
||||
1. look at the original html code,
|
||||
2. copy whatever is relevant that comes before the content into `head.html`.
|
||||
@@
|
||||
|
||||
Let's do this gradually.
|
||||
The top of the original HTML can be ignored at this point so we can start modifying starting after `</head>`.
|
||||
|
||||
Jemdoc's body starts with a Google analytics script which I'll ignore as well.
|
||||
We then have effectively one big table element.
|
||||
Stripped from its content and simplified it looks like:
|
||||
|
||||
```html
|
||||
<table id="tlayout">
|
||||
<tr valign="top">
|
||||
<td id="layout-menu">
|
||||
<div class="menu-category">jemdoc</div>
|
||||
<div class="menu-item"><a href="/" class="current">home</a></div>
|
||||
<div class="menu-category">topics</div>
|
||||
<div class="menu-item"><a href="/menu1/">Menu 1</a></div>
|
||||
<div class="menu-item"><a href="/menu2/">Menu 2</a></div>
|
||||
<div class="menu-item"><a href="/menu3/">Menu 3</a></div>
|
||||
</td>
|
||||
<td id="layout-content">
|
||||
<p> CONTENT HERE </p>
|
||||
<div id="footer">
|
||||
<div id="footer-text">
|
||||
Page generated by <a href="http://jemdoc.jaboc.net/">jemdoc</a>.
|
||||
</div>
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
```
|
||||
|
||||
Note that I've already filled in the `href=` in the links to sub-menus.
|
||||
|
||||
The "`CONTENT HERE`" part is where what Franklin generates from Markdown will go.
|
||||
Therefore, anything that is *after* that should go in `foot.html`; in our current case:
|
||||
|
||||
```html
|
||||
<!-- ... -->
|
||||
<div id="footer">
|
||||
<div id="footer-text">
|
||||
Page generated by <a href="http://jemdoc.jaboc.net/">jemdoc</a>.
|
||||
</div>
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
```
|
||||
|
||||
That's basically it (though we still have to modify the stylesheet of course).
|
||||
The `head.html` should be adapted to:
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
{{if hasmath}} {{insert head_katex.html }} {{end}}
|
||||
{{if hascode}} {{insert head_highlight.html }} {{end}}
|
||||
<link rel="stylesheet" href="/css/franklin.css">
|
||||
<link rel="stylesheet" href="/css/jemdoc.css">
|
||||
<link rel="icon" href="/assets/infra/favicon.png">
|
||||
{{isdef title}} <title>{{fill title}}</title> {{end}}
|
||||
</head>
|
||||
<body>
|
||||
<table id="tlayout">
|
||||
<tr valign="top">
|
||||
<td id="layout-menu">
|
||||
<div class="menu-category">jemdoc</div>
|
||||
<div class="menu-item"><a href="index.html" class="current">home</a></div>
|
||||
<div class="menu-category">topics</div>
|
||||
<div class="menu-item"><a href="/menu1/">Menu 1</a></div>
|
||||
<div class="menu-item"><a href="/menu2/">Menu 2</a></div>
|
||||
<div class="menu-item"><a href="/menu3/">Menu 3</a></div>
|
||||
</td>
|
||||
<td id="layout-content">
|
||||
|
||||
<!-- Content appended here -->
|
||||
```
|
||||
|
||||
and the `foot.html` should be adapted to:
|
||||
|
||||
```html
|
||||
<!-- CONTENT ENDS HERE -->
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
{{ if hasmath }}
|
||||
{{ insert foot_katex.html }}
|
||||
{{ end }}
|
||||
{{ if hascode }}
|
||||
{{ insert foot_highlight.html }}
|
||||
{{ end }}
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### Adapting the stylesheet
|
||||
|
||||
By now the page looks pretty bad:
|
||||
|
||||
![](/assets/jemdoc/jemdoc2.png)
|
||||
|
||||
the content is not centred in its box and overflows on the right, the menu looks ridiculous, time to do some CSS styling!
|
||||
|
||||
Let's start by removing everything from `_css/jemdoc.css`.
|
||||
Most of what's in there was used for the styling of the top navbar which we don't have anymore (note that the styling of the content itself is in `franklin.css`, don't change that for now; note also that `jemdoc.css` is loaded *after* `franklin.css` so that you can overwrite the styles there).
|
||||
|
||||
Let's now just copy paste the content of the [two](http://jemdoc.jaboc.net/jemdoc.css) [original](http://jemdoc.jaboc.net/jacob.css) stylesheets into ours and hope for the best, we may have some fine-tuning to do after this.
|
||||
|
||||
Doing nothing else than copy pasting already helps a lot:
|
||||
|
||||
![](/assets/jemdoc/jemdoc3.png)
|
||||
|
||||
A few things should be fixed:
|
||||
|
||||
@@tlist
|
||||
1. there's too little space at the top
|
||||
1. the menu is a bit too narrow and there's a bit too much space between the menu and the content
|
||||
1. there's not enough space after `<pre>` blocks
|
||||
@@
|
||||
|
||||
#### Fixing spacing
|
||||
|
||||
Firefox or Chrome/ium's excellent dev-tools are super helpful to fine tune stylesheets.
|
||||
Here things are pretty straightforward though.
|
||||
|
||||
First, we need to add vertical padding above `<h1>` level title:
|
||||
|
||||
```css
|
||||
h1 { padding-top: 2em; }
|
||||
```
|
||||
|
||||
Then, let's widen the menu a little
|
||||
|
||||
```css
|
||||
td#layout-menu {
|
||||
padding-left: 15px;
|
||||
padding-right: 25px;
|
||||
}
|
||||
```
|
||||
|
||||
and let's reduce the padding on the left of the `franklin-content` element:
|
||||
|
||||
```css
|
||||
.franklin-content { padding-left: 5%; }
|
||||
```
|
||||
|
||||
Finally, in the original stylesheet there is this element:
|
||||
|
||||
```css
|
||||
pre {
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
}
|
||||
```
|
||||
|
||||
which you can just remove to have a bit more space around code blocks.
|
||||
|
||||
There's probably still things that could be done to improve the layout overall (and make it more responsive!) but we'll leave it at that.
|
||||
|
||||
![](/assets/jemdoc/jemdoc4.png)
|
||||
|
||||
### Adjusting other files
|
||||
|
||||
Here we don't need to adjust anything else but, in general, you might want to adjust the other pages:
|
||||
|
||||
@@tlist
|
||||
* `head_highlight`, `head_katex`, `foot_highlight` and `foot_katex` are probably best left as they are, they will be appended if need be to pages (see in `head` and `foot` the `{{if hasmath}}` and `{{if hascode}}` blocks)
|
||||
* `page_foot` you may want to change, it defines what goes at the bottom of the `.franklin-content` div.
|
||||
@@
|
||||
|
||||
By default `page_foot` looks like
|
||||
|
||||
```html
|
||||
<div class="page-foot">
|
||||
<div class="copyright">
|
||||
© {{ fill author }}. Last modified: {{ fill fd_mtime }}. Website built with <a href="https://github.com/tlienart/Franklin.jl">Franklin.jl</a>.
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
It should be fairly straightforward to adapt that to your needs.
|
||||
|
||||
## Making a PR to the theme repo
|
||||
|
||||
Let's say you've built your own template and are pretty happy with the result and you'd like to share it for other users, great, thanks!
|
||||
|
||||
Please follow [these instructions](https://github.com/tlienart/FranklinTemplates.jl#fixingadding-a-template).
|
|
@ -1,313 +0,0 @@
|
|||
|
||||
<!--
|
||||
reviewed: 18/4/20
|
||||
-->
|
||||
|
||||
# Divs and Commands
|
||||
|
||||
\blurb{Style your content quickly and easily with custom divs, make everything reproducible and maintainable with commands.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
## Div blocks
|
||||
|
||||
In order to locally style your content, you can use `@@divname ... @@` which will wrap the content in a `<div class="divname"> ... </div>` block which you can then style as you wish in your CSS stylesheet.
|
||||
For instance, you may want to highlight some content with a light yellow background:
|
||||
|
||||
```plaintext
|
||||
Some text then
|
||||
@@important
|
||||
Some important content
|
||||
@@
|
||||
```
|
||||
|
||||
and then, in your CSS, you could use
|
||||
|
||||
```css
|
||||
.important {
|
||||
background-color: lemonchiffon;
|
||||
padding: 0.5em;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
```
|
||||
|
||||
which will look like
|
||||
|
||||
@@important
|
||||
Some important content
|
||||
@@
|
||||
|
||||
### Nesting
|
||||
|
||||
Such div blocks can be nested as in standard HTML.
|
||||
The distinction with inserting raw HTML div blocks with the `~~~...~~~` syntax is that the content of div blocks is processed as well (i.e.: can contain Franklin markdown):
|
||||
|
||||
```plaintext
|
||||
@@important
|
||||
Some text;
|
||||
@@silly-formatting
|
||||
some **silly** text with $2x+4=y$.
|
||||
@@
|
||||
and more text.
|
||||
@@
|
||||
```
|
||||
|
||||
@@important
|
||||
Some text;
|
||||
@@silly-formatting
|
||||
some **silly** text with $2x+4=y$.
|
||||
@@
|
||||
and more text.
|
||||
@@
|
||||
|
||||
## LaTeX-like commands
|
||||
|
||||
Franklin allows the definition of commands using a LaTeX-like syntax.
|
||||
This can be particularly useful for repeating elements or styling inside or outside of maths environment.
|
||||
|
||||
To define a command, you **must** use the following syntax:
|
||||
|
||||
```plaintext
|
||||
\newcommand{\name}[...]{...}
|
||||
-1- -2- -3-
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
@@flist
|
||||
1. the first bracket is the _command name_, starting with a backslash and _only made out of letters_ (lower or upper case),
|
||||
1. the second (optional) bracket indicates the _number of arguments_, if none is set the command does not take arguments,
|
||||
1. the third bracket indicates the _definition of the command_ calling `#k` to insert the $k$-th argument.
|
||||
@@
|
||||
|
||||
As in LaTeX, command definitions can be anywhere as long as they appear before they are used.
|
||||
If you want a command to be available on all your pages, put the definition in the `config.md` file.
|
||||
|
||||
\note{Franklin currently cannot just take the content of a `.tex` document and convert it, this may be (partially) supported in the future if it is deemed useful. Mainly it would require pre-defining all standard commands such as `\textbf`, `\section`, etc.}
|
||||
|
||||
### Math examples
|
||||
|
||||
If you end up writing a lot of equations on your site, defining commands can become rather useful:
|
||||
|
||||
```plaintext
|
||||
\newcommand{\R}{\mathbb R}
|
||||
|
||||
Let $f:\R\to\R$ a function...
|
||||
```
|
||||
|
||||
\newcommand{\R}{\mathbb R}
|
||||
Let $f:\R\to\R$ a function...
|
||||
|
||||
```plaintext
|
||||
\newcommand{\scal}[1]{\left\langle #1 \right\rangle}
|
||||
|
||||
$$ \mathcal W_\psi[f] = \int_\R f(s)\psi(s)\mathrm{d}s = \scal{f,\psi} $$
|
||||
```
|
||||
|
||||
\newcommand{\scal}[1]{\left\langle #1 \right\rangle}
|
||||
$$ \mathcal W_\psi[f] = \int_\R f(s)\psi(s)\mathrm{d}s = \scal{f,\psi} $$
|
||||
|
||||
### Text examples
|
||||
|
||||
Commands can also be useful outside of maths environment.
|
||||
For instance, you could define a command to quickly set the style of some text:
|
||||
|
||||
```html
|
||||
\newcommand{\styletext}[2]{~~~<span style="#1">#2</span>~~~}
|
||||
|
||||
Here is \styletext{color:magenta;font-size:14px;}{formatted text}.
|
||||
```
|
||||
|
||||
\newcommand{\styletext}[2]{~~~<span style="#1">#2</span>~~~}
|
||||
|
||||
Here is \styletext{color:magenta;font-size:14px;font-variant:small-caps;}{formatted text}.
|
||||
|
||||
### Nesting examples
|
||||
|
||||
Commands are resolved recursively which means that they can be nested and their definition can contain further Franklin markdown (again this is similar to how LaTeX works).
|
||||
|
||||
Consider for instance:
|
||||
|
||||
```plaintext
|
||||
\newcommand{\norm}[2]{\left\|#1\right\|_{#2}}
|
||||
\newcommand{\anorm}[1]{\norm{#1}{1}}
|
||||
\newcommand{\bnorm}[1]{\norm{#1}{2}}
|
||||
|
||||
Let $x\in\R^n$, there exists $0 < C_1 \le C_2$ such that
|
||||
|
||||
$$ C_1 \anorm{x} \le \bnorm{x} \le C_2\anorm{x}. $$
|
||||
```
|
||||
|
||||
\newcommand{\norm}[2]{\left\|#1\right\|_{#2}} <!--_-->
|
||||
\newcommand{\anorm}[1]{\norm{#1}{1}}
|
||||
\newcommand{\bnorm}[1]{\norm{#1}{2}}
|
||||
|
||||
Let $x\in\R^n$, there exists $0 < C_1 \le C_2$ such that
|
||||
|
||||
$$ C_1 \anorm{x} \le \bnorm{x} \le C_2\anorm{x}. $$
|
||||
|
||||
As indicated earlier, commands can contain further Franklin markdown that is processed recursively.
|
||||
For example, here is a more sophisticated example of a "definition" command such that this:
|
||||
|
||||
```plaintext
|
||||
\definition{angle between vectors}{
|
||||
Let $x, y \in \R^n$ and let $\scal{\cdot, \cdot}$ denote
|
||||
the usual inner product. Then, the angle $\theta$ between
|
||||
$x$ and $y$ is given by
|
||||
$$ \cos(\theta) = {\scal{x,y}\over \scal{x,x} \scal{y,y}}. $$
|
||||
}
|
||||
```
|
||||
|
||||
leads to this:
|
||||
|
||||
\newcommand{\definition}[2]{@@definition **Definition**: (_!#1_) #2 @@}
|
||||
|
||||
\definition{angle between vectors}{
|
||||
Let $x, y \in \R^n$ and let $\scal{\cdot, \cdot}$ denote
|
||||
the usual inner product. Then, the angle $\theta$ between $x$ and $y$ is
|
||||
given by $$ \cos(\theta) = {\scal{x,y}\over \scal{x,x} \scal{y,y}}. $$
|
||||
}
|
||||
|
||||
To do this, you would define the command:
|
||||
|
||||
```html
|
||||
\newcommand{\definition}[2]{
|
||||
@@definition
|
||||
**Definition**: (_!#1_)
|
||||
#2
|
||||
@@
|
||||
}
|
||||
```
|
||||
|
||||
and specify the styling of the `definition` div in your CSS:
|
||||
|
||||
```css
|
||||
.definition {
|
||||
background-color: aliceblue;
|
||||
border-left: 5px solid cornflowerblue;
|
||||
border-radius: 10px;
|
||||
padding: 10px;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
```
|
||||
|
||||
### Whitespaces
|
||||
|
||||
In a Franklin `newcommand`, to refer to an argument you can use `#k` or `!#k`.
|
||||
There is a small difference: the first one _introduces a space_ left of the argument while the second one does not.
|
||||
|
||||
In general whitespaces are irrelevant and will not show up on the rendered webpage so that the usual `#k` is the recommended usage.
|
||||
This helps avoid some ambiguities when resolving a chain of nested commands.
|
||||
|
||||
There are however cases where you do not want this because the whitespace does, in fact, show up.
|
||||
In such cases use `!#k` (assuming it's not ambiguous).
|
||||
|
||||
Consider for instance:
|
||||
|
||||
```plaintext
|
||||
\newcommand{\pathwith}[1]{`/usr/local/bin/#1`}
|
||||
\newcommand{\pathwithout}[1]{`/usr/local/bin/!#1`}
|
||||
|
||||
Here \pathwith{hello} is no good whereas \pathwithout{hello} is.
|
||||
```
|
||||
|
||||
\newcommand{\pathwith}[1]{`/usr/local/bin/#1`}
|
||||
\newcommand{\pathwithout}[1]{`/usr/local/bin/!#1`}
|
||||
|
||||
Here \pathwith{hello} is no good whereas \pathwithout{hello} is.
|
||||
|
||||
### Defining commands globally
|
||||
|
||||
If you define commands on a page, the command will be available only on that page; if you wish to define a command that is available on all pages, you should put the definition of the command in your `config.md` file.
|
||||
|
||||
## Hyper-references
|
||||
|
||||
Three types of hyper-references are supported in Franklin:
|
||||
|
||||
@@flist
|
||||
1. for equations in display mode,
|
||||
1. for references (bibliography),
|
||||
1. for specific anchor points in the page.
|
||||
@@
|
||||
|
||||
The syntax for all three is close to that of standard LaTeX.
|
||||
|
||||
To style the appearance of the maths or bib links in CSS, use `.franklin-content.eqref a` and `.franklin-content.bibref a` classes; for instance:
|
||||
|
||||
```css
|
||||
.franklin-content .eqref a {color: blue;}
|
||||
.franklin-content .bibref a {color: green;}
|
||||
```
|
||||
|
||||
### Equations
|
||||
|
||||
To label an equation, just use `\label{some label}` in the math environment and, to refer to it, use `\eqref{some label}`:
|
||||
|
||||
```plaintext
|
||||
Some equation:
|
||||
|
||||
$$\exp(i\pi) + 1 = 0 \label{a cool equation}$$
|
||||
|
||||
and you can refer to it in the text: equation \eqref{a cool equation}.
|
||||
```
|
||||
|
||||
As in LaTeX, you can refer to several equations in one shot by separating names with commas: `\eqref{some label, some other}` (that also means you cannot use commas in labels).
|
||||
|
||||
### References
|
||||
|
||||
For references, you can use `\biblabel{short}{name}` to declare a reference which will appear as a clickable link `(name)` or `name` and can be referred to with `short`:
|
||||
|
||||
```plaintext
|
||||
In the text you may refer to \citep{noether15, bezanson17} while in a bibliography section you would have
|
||||
|
||||
* \biblabel{noether15}{Noether (1915)} **Noether**, Korper und Systeme rationaler Funktionen, 1915.
|
||||
* \biblabel{bezanson17}{Bezanson et al. (2017)} **Bezanson**, **Edelman**, **Karpinski** and **Shah**, [Julia: a fresh approach to numerical computing](https://julialang.org/publications/julia-fresh-approach-BEKS.pdf), SIAM review 2017.
|
||||
```
|
||||
|
||||
The `name` argument therefore corresponds to how the bibliography reference will appear in the text.
|
||||
In the case above, the text will lead to
|
||||
|
||||
```plaintext
|
||||
... refer to (Noether (1915), Bezanson et al. (2017)) while ...
|
||||
```
|
||||
|
||||
You can use either
|
||||
|
||||
@@tlist
|
||||
* `\cite{short1, short2}` or `\citet{short3}`: which will not add parentheses around the link(s),
|
||||
* `\citep{short4, short5}`: which will add parentheses around the link(s).
|
||||
@@
|
||||
|
||||
As in LaTeX, if the reference is undefined on the page, the command will be replaced by **(??)**.
|
||||
|
||||
### Anchor points
|
||||
|
||||
You can specify anchor points on the page using `\label{name of the anchor}` anywhere on the page _outside_ of maths environment.
|
||||
This will insert an anchor:
|
||||
|
||||
```html
|
||||
<a id="name-of-the-anchor"></a>
|
||||
```
|
||||
|
||||
You can subsequently link to it on the same page:
|
||||
|
||||
```plaintext
|
||||
[link to it](#name-of-the-anchor)
|
||||
```
|
||||
|
||||
or from another page by prepending it with the path to the page, for instance:
|
||||
|
||||
```plaintext
|
||||
[link to it](/index.html#name-of-the-anchor)
|
||||
```
|
||||
|
||||
Note also that all section headers are anchor points for instance
|
||||
|
||||
```plaintext
|
||||
### Some subtitle
|
||||
```
|
||||
|
||||
can be linked to with `#some-subtitle`.
|
||||
If there are multiple headers with the same name, the second and subsequent ones can be referred to with `#some-subtitle__2`, `#some-subtitle__3` etc. (note the double underscore).
|
|
@ -1,431 +0,0 @@
|
|||
<!--
|
||||
reviewed: 18/4/20
|
||||
-->
|
||||
|
||||
# Markdown syntax
|
||||
|
||||
\blurb{Franklin aims to support most of Common Mark with a few differences and some useful extensions.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
## Experimenting
|
||||
|
||||
Beyond directly experimenting in a project folder, you can also explore what HTML is generated with the `fd2html` function:
|
||||
|
||||
```julia-repl
|
||||
julia> """Set `x` to 1, see [the docs](http://example.com).""" |> fd2html
|
||||
"<p>Set <code>x</code> to 1, see <a href="http://example.com">the docs</a>.</p>\n"
|
||||
```
|
||||
|
||||
## Basics
|
||||
|
||||
If you're already familiar with Markdown, you can skip this section, though it may serve as a useful reminder.
|
||||
|
||||
### Headers
|
||||
|
||||
```markdown
|
||||
# Level 1
|
||||
## Level 2
|
||||
...
|
||||
###### Level 6
|
||||
```
|
||||
|
||||
will generate the various header levels.
|
||||
|
||||
\note{Franklin makes headers into links to help with internal links and automatic table of contents generation (which you can include anywhere using `\toc`).}
|
||||
|
||||
### Text styling
|
||||
|
||||
```plaintext
|
||||
**Bold text**, *italic* or _italic_, **_bold italic_**, `inline code`.
|
||||
```
|
||||
|
||||
Inserting a horizontal rule can be done with
|
||||
|
||||
```markdown
|
||||
---
|
||||
```
|
||||
|
||||
For a blockquote, start the line with `>`:
|
||||
|
||||
```markdown
|
||||
> This is a blockquote
|
||||
|
||||
```
|
||||
|
||||
### Links
|
||||
|
||||
```markdown
|
||||
inline links: [plain link](https:://www.wikipedia.org)
|
||||
|
||||
reference links: ["reference" link][reflink] and ["reference" link][]
|
||||
|
||||
[reflink]: https://www.wikipedia.org
|
||||
["reference" link]: https://www.wikipedia.org
|
||||
```
|
||||
|
||||
Footnotes follow a similar syntax
|
||||
|
||||
```markdown
|
||||
This has a footnote[^1]
|
||||
|
||||
[^1]: footnote definition
|
||||
```
|
||||
|
||||
For images, just add an exclamation mark `!`:
|
||||
|
||||
```markdown
|
||||
inline: ![alt text](https://juliacon.org/2018/assets/img/julia-logo-dots.png)
|
||||
|
||||
reference: ![alt text][ref]
|
||||
|
||||
[ref]: https://juliacon.org/2018/assets/img/julia-logo-dots.png
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
@@tlist
|
||||
* (**link reference**) when using "indirect links" i.e. in the text you use something like `[link name][link A]` and then somewhere else you define `[link A]: some/url/`, we recommend you use unambiguous link identifiers (here `[link A]`). We recommend you to not use numbers like `[link name][1]`, indeed if on the page you have some code where `[1]` appears, there is an ambiguity for the parser,
|
||||
* (**link title**) are currently _not supported_ e.g. something like `[link A](some/url/ "link title")`,
|
||||
* (**suppress links**) if, for some reason, you want to have something like `[...]: ...` somewhere on your page that does _not_ define a link, then you need to toggle ref-links off (`@def reflinks = false`) and only use inline links `[link name](some/url/)`.
|
||||
@@
|
||||
|
||||
### Lists
|
||||
|
||||
Un-ordered list (you can also use `-`, `+` or `.` instead of `*`)
|
||||
|
||||
```markdown
|
||||
* item 1
|
||||
* item 2
|
||||
* sub-item 1
|
||||
```
|
||||
|
||||
Ordered list (the proper numbering is done automatically)
|
||||
|
||||
```markdown
|
||||
1. item 1
|
||||
1. item 2
|
||||
1. subitem 1
|
||||
```
|
||||
|
||||
\note{List items _must_ be on the same line (_this is due to [a limitation](https://github.com/JuliaLang/julia/issues/30198) of the Julia Markdown parser_).}
|
||||
|
||||
### Comments
|
||||
|
||||
You can add comments in your markdown using HTML-style comments: `<!-- your comment -->` possibly on multiple lines. Note that comments are **not** allowed in a math environment.
|
||||
|
||||
### Symbols and HTML entities
|
||||
|
||||
Outside code environments, there are a few quirks in dealing with symbols:
|
||||
|
||||
@@tlist
|
||||
* (**dollar sign**) to introduce a dollar sign, you _must_ escape it with a backslash: `\$` as it is otherwise used to open and close inline math blocks,
|
||||
* (**HTML entity**) you can use HTML entities without issues like `→` for "→" or `$` for "\$",
|
||||
* (**backslash**) to introduce a backslash, you can just use ~~~<code>\</code>~~~, while a _double backslash_ ~~~<code>\\</code>~~~ can be used to specify a _line break_ in text.
|
||||
@@
|
||||
|
||||
## Table of contents
|
||||
|
||||
Franklin can insert an automatically generated table of contents simply by using `\toc` or `\tableofcontents` somewhere appropriate in your markdown.
|
||||
The table of contents will be generated in a `franklin-toc` div block, so if you would like to modify the styling, you should modify `.franklin-toc ol`, `.franklin-toc li` etc in your CSS.
|
||||
|
||||
You can specify the minimum and maximum header level to control the table of contents nesting using `@def mintoclevel=2` and `@def maxtoclevel=3` where, here, it would build a table of contents with the `h2` and `h3` headers only (this is the setting used here for instance).
|
||||
|
||||
## Code
|
||||
|
||||
Inline code with single and double back-ticks
|
||||
|
||||
```markdown
|
||||
Single back-ticks: `var = 5`, and
|
||||
double back-ticks if the code includes ticks: ``var = "`"``.
|
||||
```
|
||||
|
||||
Blocks of code with triple back-ticks and the language specifier
|
||||
|
||||
`````markdown
|
||||
```julia
|
||||
a = 5
|
||||
println(a)
|
||||
```
|
||||
`````
|
||||
|
||||
You're not obliged to specify the language, if you don't it will assume the language corresponds to the [page variable](/syntax/page-variables/) `lang` (set to `julia` by default).
|
||||
If you want the block to be considered as plaintext, use `plaintext` as the language specifier.
|
||||
|
||||
Finally you can also use indented code blocks (which will also take its highlighting hint from `lang`) but this is **not recommended** and you have to explicitly opt-in by setting `indented_code` on a page that would use them:
|
||||
|
||||
```markdown
|
||||
@def indented_code = true
|
||||
Code block:
|
||||
|
||||
a = 5
|
||||
println(a)
|
||||
|
||||
```
|
||||
|
||||
Indented code blocks are _ambiguous_ with how other Franklin blocks can be defined such as div blocks and latex blocks. If you really want to use them, you will have to ensure that your div blocks and latex commands on that page do **not use** indentation as it might cause problems.
|
||||
|
||||
### Highlighting
|
||||
|
||||
Syntax highlighting is done via [highlight.js](https://highlightjs.org/) and you can find the relevant script in the `/_libs/highlight/` folder.
|
||||
The default one supports highlighting for Bash, CSS, Ini, Julia, Julia-repl, Markdown, plaintext, Python, R, Ruby, Xml and Yaml.
|
||||
Note that if you use pre-rendering, then the full `highlight.js` is used with support for over 100 languages.
|
||||
|
||||
By default unfenced code blocks (e.g. indented code blocks) will be highlighted as Julia code blocks; to change this, set `@def lang = "python"`.
|
||||
If you want a code block to _not_ be highlighted, we recommend you use `plaintext` to guarantee this:
|
||||
|
||||
`````markdown
|
||||
```plaintext
|
||||
this will not be highlighted
|
||||
```
|
||||
`````
|
||||
|
||||
If you wish to have higlighting for more languages outside of the pre-rendering mode, head to [highlight.js](https://highlightjs.org/), make a selection of languages and place the resulting `higlight.pack.js` in the `/_libs/highlight/` folder.
|
||||
If you do this, you might want to slightly modify it to ensure that the Julia-repl mode is properly highlighted (e.g. `shell>`):
|
||||
|
||||
@@tlist
|
||||
* open the `highlight.pack.js` in an editor of your choice
|
||||
* look for `hljs.registerLanguage("julia-repl"` and modify the entry to:
|
||||
@@
|
||||
|
||||
```javascript
|
||||
hljs.registerLanguage("julia-repl",function(a){return{c:[{cN:"meta",b:/^julia>/,r:10,starts:{e:/^(?![ ]{6})/,sL:"julia"}},{cN:"metas",b:/^shell>/,r:10,starts:{e:/^(?![ ]{6})/,sL:"bash"}},{cN:"metap",b:/^\(.*\)\spkg>/,r:10,starts:{e:/^(?![ ]{6})/,sL:"julia"}}]}});
|
||||
```
|
||||
|
||||
(see also [the README](https://github.com/tlienart/FranklinTemplates.jl#notes) of FranklinTemplates).
|
||||
|
||||
### Evaluated code blocks
|
||||
|
||||
Julia code blocks can be evaluated and the result of the code either shown or rendered.
|
||||
To declare a code block for evaluation, use the fenced code block syntax with a name for the code block:
|
||||
|
||||
`````markdown
|
||||
```julia:snippet1
|
||||
using LinearAlgebra, Random
|
||||
Random.seed!(555)
|
||||
a = randn(5)
|
||||
round(norm(a), sigdigits=4)
|
||||
```
|
||||
|
||||
\show{snippet1}
|
||||
`````
|
||||
|
||||
This will look like
|
||||
|
||||
```julia:snippet1
|
||||
using LinearAlgebra, Random
|
||||
Random.seed!(555)
|
||||
a = randn(5)
|
||||
round(norm(a), sigdigits=4)
|
||||
```
|
||||
|
||||
\show{snippet1}
|
||||
|
||||
For more information on using evaluated code blocks, please head to the [section on code insertion](/code/).
|
||||
|
||||
## Maths
|
||||
|
||||
### Inline and display maths
|
||||
|
||||
Inserting maths is done pretty much like in LaTeX:
|
||||
|
||||
```plaintext
|
||||
Inline: $x=5$ or display:
|
||||
|
||||
$$ \mathcal W_\psi[f] = \int_{\mathbb R} f(s)\psi(s)\mathrm{d}s $$
|
||||
```
|
||||
|
||||
Inline: $x=5$ or display:
|
||||
|
||||
$$ \mathcal W_\psi[f] = \int_{\mathbb R} f(s)\psi(s)\mathrm{d}s $$
|
||||
|
||||
You can also use `\[...\]` for display maths.
|
||||
|
||||
One thing to keep in mind when adding maths on your page is that you should be generous in your use of whitespace, particularly around inequality operators to avoid ambiguity that could confuse KaTeX.
|
||||
So for instance prefer: `$0 < C$` to `$0<C$` (the latter will not render properly).
|
||||
Also if you have to write double braces, make sure to add a space in between so `{ {` or `} }` and not `{{` or `}}` since that has a specific meaning in Franklin:
|
||||
|
||||
```plaintext
|
||||
$$ \dfrac{ {101}_{2} } $$
|
||||
```
|
||||
|
||||
$$\dfrac{1}{ {101}_{2} }$$
|
||||
|
||||
|
||||
### Aligned maths
|
||||
|
||||
For aligned environment you can use `\begin{eqnarray}...\end{eqnarray}` or `\begin{align}...\end{align}`
|
||||
|
||||
```markdown
|
||||
\begin{eqnarray}
|
||||
\exp(i\pi)+1 &=& 0\\
|
||||
1+1 &=& 2
|
||||
\end{eqnarray}
|
||||
|
||||
\begin{align}
|
||||
\exp(i\pi)+1 &= 0\\
|
||||
1+1 &= 2
|
||||
\end{align}
|
||||
```
|
||||
|
||||
\begin{eqnarray}
|
||||
\exp(i\pi)+1 &=& 0\\
|
||||
1+1 &=& 2
|
||||
\end{eqnarray}
|
||||
|
||||
\begin{align}
|
||||
\exp(i\pi)+1 &= 0\\
|
||||
1+1 &= 2
|
||||
\end{align}
|
||||
|
||||
\note{In proper LaTeX, the use of `\eqnarray` is discouraged due to possible interference with array column spacing. In Franklin this does not happen and so the only practical difference is that `\eqnarray` will give you a bit more horizontal spacing around the `=` signs.}
|
||||
|
||||
## Raw HTML
|
||||
|
||||
You can inject raw HTML by fencing it with `~~~...~~~` which can be useful for custom formatting.
|
||||
|
||||
A simple example is if you want to colour your text; for instance with
|
||||
|
||||
```html
|
||||
~~~
|
||||
<span style="color:magenta;">coloured</span>
|
||||
~~~
|
||||
```
|
||||
|
||||
you get: some ~~~<span style="color:magenta;">coloured</span>~~~ text (note that it all can be on a single line.)
|
||||
|
||||
You could also use this to locally customise a layout etc.
|
||||
|
||||
\note{Inside a raw HTML block, you cannot use markdown, maths, etc. For this reason, it is often preferable to use nested `@@divname...@@` blocks instead of raw HTML since those _can_ have markdown, maths, etc. in them. (See [inserting divs](/syntax/divs-commands/).)}
|
||||
|
||||
## File insertions
|
||||
A few commands are defined to help you with insertions of content; you can also define your own commands using custom HTML as was discussed before.
|
||||
|
||||
### Inserting a figure
|
||||
|
||||
The commands
|
||||
@@tlist
|
||||
* `\figalt{alt}{path}`, and
|
||||
* `\fig{path}`
|
||||
@@
|
||||
are convenient commands to insert figures.
|
||||
Of course you're free to use the default markdown way `![alt](full_path)` instead.
|
||||
One difference with these commands though is that they allow the use of relative paths; this can be convenient in order to organise your assets as you organise your pages.
|
||||
|
||||
**Note**: to help with the organisation of assets, Franklin will assume by default that figures are placed in a folder `/output/` relative to where the script is, i.e. if the script is in `[script_dir]`, the figures will be in `[script_dir]/output/`. To help with this, the macro `@OUTPUT` can be used which specifies the path to this relative output dir:
|
||||
|
||||
`````
|
||||
```julia:./ex1
|
||||
using PyPlot
|
||||
figure()
|
||||
plot([0, 1], [0, 1])
|
||||
savefig(joinpath(@OUTPUT, "test.png"))
|
||||
```
|
||||
\fig{./output/test}
|
||||
`````
|
||||
|
||||
This gives:
|
||||
|
||||
```julia:./ex1
|
||||
using PyPlot
|
||||
figure()
|
||||
plot([0, 1], [0, 1])
|
||||
savefig(joinpath(@OUTPUT, "test.png"))
|
||||
```
|
||||
|
||||
@@small-img
|
||||
\fig{./output/test}
|
||||
@@
|
||||
|
||||
In fact the syntax `\fig{./test}` is also allowed, Franklin will then first look in the `[script_dir]` for a `test.*` figure and, if it doesn't find one, will try to look in `[script_dir]/output/` for a `test.*` figure:
|
||||
|
||||
@@small-img
|
||||
\fig{./test}
|
||||
@@
|
||||
|
||||
\note{Remember that these docs are written in Franklin so you can inspect the source directory if you would like to see the source markdown.}
|
||||
|
||||
### Inserting markdown
|
||||
|
||||
In some situation, you may have some markdown in a file which you might want to include somewhere else.
|
||||
This can be achieved thanks to the `\textinput{path}` commmand.
|
||||
The path specification is as the other commands, and the text will be formatted.
|
||||
|
||||
As an example you could have in `/assets/ccc/sidefile.md`:
|
||||
|
||||
|
||||
```markdown
|
||||
some **markdown** in a side file.
|
||||
```
|
||||
|
||||
whereas in `index.md`:
|
||||
|
||||
```markdown
|
||||
This is the index then \textinput{ccc/sidefile}
|
||||
```
|
||||
|
||||
and this will be equivalent to just having in `index.md`:
|
||||
|
||||
```markdown
|
||||
This is the index then some **markdown** in a side file.
|
||||
```
|
||||
|
||||
**Note**: if you don't specify a file extension, `.md` is appended to the specified path.
|
||||
|
||||
### Inserting a table
|
||||
|
||||
You can insert tables directly from CSV files with the `\tableinput{header}{path}` command.
|
||||
If you generate the file on-the-fly, you should follow this example:
|
||||
|
||||
`````
|
||||
```julia:./tableinput/gen
|
||||
testcsv = "h1,h2,h3
|
||||
152,some string, 1.5f0
|
||||
0,another string,2.87"
|
||||
write("assets/pages/tableinput/testcsv.csv", testcsv)
|
||||
```
|
||||
`````
|
||||
|
||||
Then you can insert the table with:
|
||||
|
||||
`````
|
||||
\tableinput{}{./tableinput/testcsv.csv}
|
||||
`````
|
||||
|
||||
Which will result in:
|
||||
|
||||
| h1 | h2 | h3 |
|
||||
| --- | -------------- | ----- |
|
||||
| 152 | some string | 1.5f0 |
|
||||
| 0 | another string | 2.87 |
|
||||
|
||||
In this case, given no header was specified in the call, a header was generated from the first line in the CSV (here: `h1, h2, h3`).
|
||||
|
||||
If your file doesn't have a header, you can specify it in the call:
|
||||
|
||||
`````
|
||||
```julia:./tableinput/gen
|
||||
testcsv = "152,some string, 1.5f0
|
||||
0,another string,2.87"
|
||||
write("assets/pages/tableinput/testcsv2.csv", testcsv)
|
||||
```
|
||||
\tableinput{custom h1,custom h2,custom h3}{./tableinput/testcsv2.csv}
|
||||
`````
|
||||
|
||||
| custom h1 | custom h2 | custom h3 |
|
||||
| --------- | -------------- | --------- |
|
||||
| 152 | some string | 1.5f0 |
|
||||
| 0 | another string | 2.87 |
|
||||
|
||||
With the above in mind, you can also include existing CSV files.
|
||||
|
||||
\note{The look of the table will be defined by your CSS stylesheet.}
|
||||
|
||||
There's a couple of rules that you have to keep in mind when using the `\tableinput{}{}` command:
|
||||
|
||||
@@tlist
|
||||
* Columns must be separated by a comma (`,`).
|
||||
* If a header is specified, its length must match the number of columns in the file.
|
||||
@@
|
|
@ -1,272 +0,0 @@
|
|||
@def hascode=true
|
||||
|
||||
# Page variables
|
||||
|
||||
<!--
|
||||
reviewed: Apr 19, 2020
|
||||
-->
|
||||
|
||||
|
||||
|
||||
\blurb{Page variables offer a straightforward way to interact with the HTML templating from the markdown.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
## Overview
|
||||
|
||||
The general syntax to define a page variable is to write `@def varname = value` on a new line e.g.:
|
||||
|
||||
```
|
||||
@def author = "Septimia Zenobia"
|
||||
```
|
||||
|
||||
where you could set the variable to a string, a number, a date,... anything. Definitions can span multiple lines but if they do, the subsequent lines **must** be indented e.g.:
|
||||
|
||||
```
|
||||
@def some_str = """A string
|
||||
on several lines is ok
|
||||
but lines must be indented"""
|
||||
```
|
||||
|
||||
These variables can serve multiple purposes but, primarily, they can be accessed from the HTML template blocks e.g.:
|
||||
|
||||
```html
|
||||
<footer>
|
||||
This is the footer. © {{fill author}}.
|
||||
</footer>
|
||||
```
|
||||
|
||||
which could be useful as footer on all pages.
|
||||
|
||||
The syntax `{{ ... }}` indicates a HTML _function_, `fill` is the function name and the rest of the bracket elements are _page variables_ (here `author`) serving as arguments of the function.
|
||||
|
||||
_Local_ page variables denote variables that are defined on a single page and accessible on that page only by contrast to _global_ page variables which are set globally (in the `config.md` file) and accessible on all pages.
|
||||
|
||||
In both cases there are _default_ page variables with default values which you can change and use.
|
||||
You can also define your own variables, both global and local.
|
||||
|
||||
### Using page variables
|
||||
|
||||
Both local and global page variables are meant for essentially two purposes:
|
||||
|
||||
@@tlist
|
||||
1. control the HTML template from the markdown,
|
||||
1. modify how Franklin generates HTML.
|
||||
@@
|
||||
|
||||
The second one is a bit less prevalent but, for instance, you can specify the default programming language for all code blocks so that code blocks that don't specify a language would use the default language for highlighting:
|
||||
|
||||
```
|
||||
@def lang = "julia"
|
||||
```
|
||||
|
||||
In the first case, you can access variables in your HTML template via one of the HTML functions such as the `fill` function shown above.
|
||||
|
||||
## HTML functions
|
||||
|
||||
HTML functions can be used in any one of your `*.html` file and in particular in any of the `_layout/*.html` files such as `head.html`.
|
||||
They are always called with the syntax `{{fname pv1 pv2 ...}}` where `pv1 pv2 ...` are page variable names.
|
||||
|
||||
### Basic functions
|
||||
|
||||
A few functions are available with the `{{fill ...}}` arguably the most likely to be of use.
|
||||
|
||||
@@lalign
|
||||
| Format | Role |
|
||||
| :----: | :--: |
|
||||
| `{{fill vname}}` or `{{vname}}` | place the value of page variable `vname`
|
||||
| `{{fill vname rpath}}` | same but taking the value from the page at `rpath` where `rpath` is a relative path like `blog/pg1`
|
||||
| `{{insert fpath}}` | insert the content of the file at `fpath`
|
||||
| `{{href vname}}` | inserts a reference (_mostly internal use_)
|
||||
| `{{toc}}` | places a table of content (_mostly internal use_)
|
||||
@@
|
||||
|
||||
The `{{insert fpath}}` can be useful if you want to include specific HTML scaffolding on some pages, for instance in example pages you will see in the `head.html`:
|
||||
|
||||
```html
|
||||
{{if hasmath}} {{insert head_katex.html}} {{end}}
|
||||
```
|
||||
|
||||
### Conditional blocks
|
||||
|
||||
Conditional blocks allow to specify which parts of the HTML template should be active depending on the value of given page variable(s).
|
||||
The format follows this structure:
|
||||
|
||||
```html
|
||||
{{if vname}}
|
||||
...
|
||||
{{elseif vname2}}
|
||||
...
|
||||
{{else}}
|
||||
...
|
||||
{{end}}
|
||||
```
|
||||
|
||||
where `vname` and `vname2` are expected to be page variable evaluating to a boolean.
|
||||
Of course you don't have to specify the `{{elseif ...}}` or `{{else}}` if you don't need them.
|
||||
|
||||
\note{
|
||||
The conditional blocks are fairly basic; in particular operations between page variables are not supported, so you can't write something like `{{if hasmath && hascode}}`.
|
||||
For more complex use cases, consider defining your own HTML functions using the [utils file](/syntax/utils/).
|
||||
}
|
||||
|
||||
You can also use some dedicated conditional blocks:
|
||||
|
||||
@@lalign
|
||||
| Format | Role |
|
||||
| :----: | :--: |
|
||||
| `{{ispage path/to/page}}` | whether the current page corresponds to the path
|
||||
| `{{isnotpage path/to/page}}` | opposite of previous
|
||||
| `{{isdef vname}}` | whether `vname` is defined
|
||||
| `{{isnotdef vname}}` | opposite of previous
|
||||
@@
|
||||
|
||||
The `{{ispage ...}}` and `{{isnotpage ...}}` accept `*` as joker symbol; for instance `{{ispage maths/*}}` is allowed.
|
||||
|
||||
**Note**: for the `C` users out there, you can also use `ifdef`, `ifndef`.
|
||||
|
||||
Consider the following example (very similar to what is used on the current page):
|
||||
|
||||
```html
|
||||
<li class="{{ispage syntax/*}}active{{end}}">• Syntax
|
||||
<ul>
|
||||
<!-- ... -->
|
||||
<li class="{{ispage syntax/page-variables}}active{{end}}">Page Variables
|
||||
<!-- ... -->
|
||||
</ul>
|
||||
```
|
||||
|
||||
This allows a simple, javascript-free, way of having a navigation menu that is styled depending on which page is currently active.
|
||||
|
||||
### For loops
|
||||
|
||||
You can define iterable page variables (array, tuple, ...) and loop over them using the following syntax:
|
||||
|
||||
```html
|
||||
{{for x in vname}}
|
||||
...{{fill x}}...
|
||||
{{end}}
|
||||
```
|
||||
|
||||
Only `{{fill vname}}` and `{{fill vname rpath}}` are allowed in such a for loop. You can also unpack an iterable like
|
||||
|
||||
```html
|
||||
{{for (x, y) in vname}}
|
||||
...{{fill x}}...{{fill y}}
|
||||
{{end}}
|
||||
```
|
||||
|
||||
where `vname` would refer to something like `[(1,2),(3,4)]`.
|
||||
|
||||
## Global page variables
|
||||
|
||||
The table below list global page variables that you can set.
|
||||
These variables are best defined in your `config.md` file though you can overwrite the value locally by redefining the variable on a given page (this will then only have an effect on that page).
|
||||
|
||||
@@lalign
|
||||
| Name | Type(s) | Default value | Comment
|
||||
| :--: | :-----: | :-----------: | :-----:
|
||||
| `author` | `String, Nothing` | `"THE AUTHOR"` |
|
||||
| `autocode` | `Bool` | `true` | whether to detect the presence of code blocks and set the local var `hascode` automatically
|
||||
| `automath` | `Bool` | `true` | whether to detect the presence of math blocks and set the local var `hasmath` automatically
|
||||
| `date_format` | `String` | `"U dd, yyyy"` | Must be a format recognised by Julia's `Dates.format`
|
||||
| `date_days` | `Vector{String}` | `String[]` | Names for days of the week (\*)
|
||||
| `date_shortdays` | `Vector{String}` | `String[]` | Short names for the days of the week (\*)
|
||||
| `date_months` | `Vector{String}` | `String[]` | Names for months (\*)
|
||||
| `date_shortmonths` | `Vector{String}` | `String[]` | Short names for months (\*)
|
||||
| `div_content` | `String` | `"franklin-content"` | Name of the div that will englobe the processed content between `head` and `foot`
|
||||
| `ignore` | `Vector{String}` | `String[]` | Files that should be ignored by Franklin (\*\*)
|
||||
| `prepath` | `String` | `""` | Use if your website is a project website (\*\*\*)
|
||||
| `website_title`| `String` | `""` | (RSS) (\*\*\*\*)
|
||||
| `website_descr`| `String` | `""` | (RSS)
|
||||
| `website_url` | `String` | `""` | (RSS)
|
||||
| `generate_rss` | `Bool` | `true` |
|
||||
| `folder_structure` | `VersionNumber` | `v"0.2"` | only relevant for users of Franklin < 0.5, see [NEWS.md](http://github.com/tlienart/Franklin.jl/NEWS.md)
|
||||
@@
|
||||
|
||||
**Notes**:\\
|
||||
\smindent{(\*)} \smnote{must be in a format recognized by Julia's `Dates.DateLocale`. Defaults to English. If left unset, the short names are created automatically by using the first three characters of the full names.}\\
|
||||
\smindent{(\*\*)} \smnote{to ignore a file add it's relative path like `"path/to/file.md"`, to ignore a directory end the path with a `/` like `"path/to/dir/"`.}\\
|
||||
\smindent{(\*\*\*)} \smnote{say you're using GitHub pages and your username is `darth`, by default Franklin will assume the root URL to be `darth.github.io/`. However, if you want to build a project page so that the base URL is `darth.github.io/vador/` then use `@def prepath = "vador"`}.\\
|
||||
\smindent{(\*\*\*\*)} \smnote{these **must** be defined for RSS to be generated for your site (on top of `generate_rss` being `true`). See also the [RSS subsection](#rss) below}.
|
||||
|
||||
## Local page variables
|
||||
|
||||
The tables below list local page variables that you can set.
|
||||
These variables are typically set locally on a page.
|
||||
Remember that:
|
||||
@@tlist
|
||||
- you can also define your own variables (with different names),
|
||||
- you can change the default value of a variable by defining it in your `config.md`.
|
||||
@@
|
||||
Note that variables shown below that have a name starting with `fd_` are _not meant to be defined_ as their value is typically computed on the fly (but they can be used).
|
||||
|
||||
### Basic settings
|
||||
|
||||
@@lalign
|
||||
| Name | Type | Default value | Comment
|
||||
| ---- | ---- | ------------- | -------
|
||||
| `title` | `String, Nothing` | `nothing` | page title (\*)
|
||||
| `hasmath` | `Bool` | `true` | whether to activate KaTeX for that page
|
||||
| `hascode` | `Bool` | `false` | whether to activate highlight.js for that page
|
||||
| `date` | `String, Date, Nothing` | `Date(1)` | a date object (e.g. if you want to set a publication date)
|
||||
| `lang` | `String` | `julia` | default highlighting for code on the page
|
||||
| `reflinks` | `Bool` | `true` | whether there are things like `[ID]: URL` on your page (\*\*)
|
||||
| `indented_code` | `Bool` | `false` | whether indented blocks should be considered as code (\*\*\*)
|
||||
| `mintoclevel` | `Int` | `1` | minimum title level to go in the table of content (often you'll want this to be `2`)
|
||||
| `maxtoclevel` | `Int` | `10` | maximum title level to go in the table of content
|
||||
| `fd_ctime` | `Date` | | time of creation of the markdown file
|
||||
| `fd_mtime` | `Date` | | time of last modification of the markdown file
|
||||
| `fd_rpath` | `String` | | relative path to file `[(...)/thispage.md]`
|
||||
@@
|
||||
|
||||
**Notes**:\\
|
||||
\smindent{(\*)} \smnote{if the title is not set, the first header will be used as title}.\\
|
||||
\smindent{(\*\*)} \smnote{there may be cases where you want to literally type `]:` in some code without it indicating a link reference. In such case, set `reflinks` to `false` to avoid ambiguities}.\\
|
||||
\smindent{(\*\*\*)} \smnote{it is recommended to fence your code blocks (use backticks) as it's not ambiguous for the parser whereas indented blocks can be. If you do want to use indented blocks as code blocks, it's your responsibility to make sure there are no ambiguities}.
|
||||
|
||||
### Code evaluation
|
||||
|
||||
For more informations on these, see the section on [inserting and evaluating code](/code/).
|
||||
|
||||
@@lalign
|
||||
| Name | Type | Default value | Comment
|
||||
| ---- | ---- | ------------- | -------
|
||||
| `reeval` | `Bool` | `false` | whether to reevaluate all code blocks on the page
|
||||
| `showall` | `Bool` | `false` | notebook mode if `true` where the output of the code block is shown below
|
||||
| `fd_eval` | `Bool` | `false` | internal variable to keep track of whether the scope is stale (in which case all subsequent blocks are re-evaluated)
|
||||
@@
|
||||
|
||||
### RSS
|
||||
|
||||
These are variables related to [RSS 2.0 specifications](https://cyber.harvard.edu/rss/rss.html) and must match the format indicated there.
|
||||
If you want proper RSS to be generated, you **must** define at least the `rss_description` or `rss` (which is an alias for `rss_description`).
|
||||
All these variables expect a `String`.
|
||||
|
||||
@@lalign
|
||||
| Name | Default value |
|
||||
| ---- | ------------- |
|
||||
| `rss`, `rss_description` | `""` |
|
||||
| `rss_title` | current page title |
|
||||
| `rss_author` | current author |
|
||||
| `rss_category` | `""` |
|
||||
| `rss_comments` | `""` |
|
||||
| `rss_enclosure` | `""` |
|
||||
| `rss_pubdate` | `""` |
|
||||
@@
|
||||
|
||||
To recapitulate, for a working RSS feed to be generated you need:
|
||||
|
||||
@@tlist
|
||||
- to set the `website_*` variables in your `config.md` (see [global page variables](#global_page_variables)),
|
||||
- on appropriate pages, to define at least `rss` to a valid description.
|
||||
@@
|
||||
|
||||
For an example, see [this mirror of the Julia blog posts](https://github.com/cormullion/julialangblog) with:
|
||||
|
||||
@@tlist
|
||||
- [the config file](https://github.com/cormullion/julialangblog/blob/master/src/config.md)
|
||||
- an [example of page](https://github.com/cormullion/julialangblog/blob/master/src/pages/2012-02-14-why-we-created-julia.md).
|
||||
@@
|
|
@ -1 +0,0 @@
|
|||
# Utils
|
|
@ -1,166 +0,0 @@
|
|||
<!--
|
||||
reviewed: 18/4/20
|
||||
-->
|
||||
|
||||
# Deploying your website
|
||||
|
||||
\blurb{Set it up once then don't think about it.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
\lineskip
|
||||
|
||||
Deploying the website is trivial on Gitlab and services like Netlify. On GitHub there are a few extra steps **especially if you want a user/org website**.
|
||||
|
||||
## Deploying on GitHub
|
||||
|
||||
**Warning**: the setup to synchronise your local folder and the remote repository is _different_ based on whether you want a user/org website:
|
||||
@@tlist
|
||||
* a _user_ website has a base URL looking like `username.github.io`.
|
||||
* a _project_ website has a base URL looking like `username.github.io/project/`.
|
||||
@@
|
||||
Make sure to follow the appropriate instructions!
|
||||
|
||||
### Creating a repo on GitHub
|
||||
|
||||
Start by creating an empty GitHub repository
|
||||
|
||||
@@tlist
|
||||
* for a personal (or org) website the repository **must** be named `username.github.io` (or `orgname.github.io`) see also [the github pages docs](https://pages.github.com/),
|
||||
* for a project website the repo can be named anything you want, let's say `myWebsite`.
|
||||
@@
|
||||
|
||||
### Adding access tokens
|
||||
|
||||
In order for the deployment action to work on GitHub, you need to set up an access token on GitHub. The steps are explained below but you [can read more on the topic here](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
|
||||
|
||||
**STEP 1**:
|
||||
|
||||
@@tlist
|
||||
* Make a public/private key pair on your local machine with `ssh-keygen -N "" -f franklin` ([see also here](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) for more information about generating ssh keys).
|
||||
* This creates 2 files, the private key: `franklin`, and the public key `franklin.pub`.
|
||||
@@
|
||||
|
||||
**STEP 2**:
|
||||
|
||||
@@tlist
|
||||
* Go to the repository and select *Settings > Secrets* then click on **Add new secret**,
|
||||
* Name the secret `FRANKLIN_PRIV` and copy the contents of the **private key** (`franklin`) from the previous step.
|
||||
@@
|
||||
|
||||
![](/assets/img/add_secret.png)
|
||||
|
||||
**STEP 3**:
|
||||
|
||||
@@tlist
|
||||
* Go to the repository and select *Settings > Deploy keys* then click on **Add deploy key**,
|
||||
* Name the deploy key `FRANKLIN_PUB` and copy the contents of the **public key** (`franklin.pub`) from step 1.
|
||||
* Give the key write access.
|
||||
@@
|
||||
|
||||
![](/assets/img/add_deploy_key.png)
|
||||
|
||||
**STEP 4**:
|
||||
|
||||
Remove both files (`franklin`, `franklin.pub`) from your local folder.
|
||||
|
||||
### Synchronise your local folder [User/Org website]
|
||||
|
||||
> This assumes that you're working on a user folder with base URL looking like `username.github.io`. See [this example](https://github.com/tlienart2/tlienart2.github.io) for instance.
|
||||
|
||||
You need to synchronise your repository and your local website folder; to do so, go to your terminal, `cd` to the website folder and follow the steps below:
|
||||
|
||||
@@tlist
|
||||
- `git init && git remote add origin URL_TO_YOUR_REPO`
|
||||
- `git checkout -b dev`
|
||||
- `git add -A && git commit -am "initial files"`
|
||||
@@
|
||||
|
||||
It is **crucial** to change the branch to `dev` (or any other name that you like that is not `master`).
|
||||
This is because a user/org site **must** be deployed from the `master` branch on GitHub.
|
||||
|
||||
Now, in an editor, open the file [`.github/workflows/deploy.yml`](https://github.com/tlienart2/tlienart2.github.io/blob/dev/.github/workflows/deploy.yml) and change the `on` section to
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- dev
|
||||
```
|
||||
|
||||
change also the `BRANCH` line at the end to `BRANCH: master`:
|
||||
|
||||
```yaml
|
||||
BRANCH: master
|
||||
FOLDER: __site
|
||||
```
|
||||
|
||||
With all this, if you push changes to `dev` with
|
||||
|
||||
```
|
||||
git push -u origin dev
|
||||
```
|
||||
|
||||
the GitHub action will be triggered and deploy the content of the `__site` folder to the `master` branch.
|
||||
GitHub pages will then deploy the website from the master branch.
|
||||
|
||||
\note{It takes a couple of minutes for the whole process to complete and your site to be available online.}
|
||||
|
||||
\note{It is recommended to change your default branch on the repository to `dev` (GitHub may have done that automatically for you). To do this, click on *Settings > Branches* and select the default branch.}
|
||||
|
||||
### Synchronise your local folder [Project website]
|
||||
|
||||
> This assumes that you're working on a user folder with base URL looking like `username.github.io/myWebsite`. See [this example](https://github.com/tlienart2/myWebsite) for instance.
|
||||
|
||||
Now you need to synchronise your repository and your local website folder; to do so, go to your terminal, `cd` to the website folder and follow the steps below:
|
||||
|
||||
@@tlist
|
||||
- `git init && git remote add origin URL_TO_YOUR_REPO`
|
||||
- `git add -A && git commit -am "initial files"`
|
||||
@@
|
||||
|
||||
That's it! when you push your updates to the `master` branch, the [GitHub action](https://github.com/tlienart2/myWebsite/blob/master/.github/workflows/deploy.yml) will deploy the `__site` folder to a `gh-pages` branch that GitHub Pages will then use to deploy your website.
|
||||
|
||||
\note{It takes a couple of minutes for the whole process to complete and your site to be available online.}
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
@@tlist
|
||||
- Make sure you have set the access tokens properly,
|
||||
- Make sure GitHub Pages is pointing at the right branch (see screenshot below),
|
||||
- Open an issue on Franklin's GitHub or ask on the **#franklin** juliaslack channel.
|
||||
@@
|
||||
|
||||
![](/assets/img/deploy_branch.png)
|
||||
|
||||
## Deploying on GitLab
|
||||
|
||||
### Creating a repo on GitLab
|
||||
|
||||
Start by creating an empty GitLab repository
|
||||
|
||||
@@tlist
|
||||
* for a personal website the repository **must** be named `username.gitlab.io` see also [the gitlab pages docs](https://about.gitlab.com/stages-devops-lifecycle/pages/),
|
||||
* for a project website the repo can be named anything you want.
|
||||
@@
|
||||
|
||||
### Synchronise your local folder
|
||||
|
||||
Now you need to synchronise your repository and your local website folder; to do so, go to your terminal, `cd` to the website folder and follow the steps below:
|
||||
|
||||
@@tlist
|
||||
- `git init && git remote add origin URL_TO_YOUR_REPO`
|
||||
- `git add -A && git commit -am "initial files"`
|
||||
@@
|
||||
|
||||
That's it! when you push your updates to the `master` branch, the GitLab CI will copy the `__site` folder to a virtual `public` folder and deploy its content.
|
||||
|
||||
\note{It takes a couple of minutes for the whole process to complete and your site to be available online.}
|
||||
|
||||
## Deploying on Netlify
|
||||
|
||||
Synchronise your local website folder with a repository (e.g. a GitHub or GitLab repository) then select that repository on Netlify and indicate you want to deploy the `__site` folder.
|
||||
|
||||
That's it!
|
|
@ -1,197 +0,0 @@
|
|||
<!--
|
||||
reviewed: 18/4/20
|
||||
-->
|
||||
|
||||
# Working with Franklin
|
||||
|
||||
\blurb{Set things up in minutes and focus on writing great content.}
|
||||
|
||||
\lineskip
|
||||
|
||||
\toc
|
||||
|
||||
## Creating your website
|
||||
|
||||
To get started, the easiest is to use the `newsite` function to generate a website folder which you can then modify to your heart's content.
|
||||
The command takes one mandatory argument: the _name_ of the folder (which can be `"."` if you want to set things up in your current directory).
|
||||
You can optionally specify a template:
|
||||
|
||||
```julia-repl
|
||||
julia> newsite("TestWebsite"; template="vela")
|
||||
✓ Website folder generated at "TestWebsite" (now the current directory).
|
||||
→ Use serve() from Franklin to see the website in your browser.
|
||||
```
|
||||
|
||||
There are a number of [simple templates](https://tlienart.github.io/FranklinTemplates.jl/) you can choose from and tweak.
|
||||
|
||||
\note{The templates are meant to be used as _starting points_ and will likely require some fixes to match what you want. Your help to make them better is very welcome.}
|
||||
|
||||
Once you have created a new website folder, you can start the live-rendering of your website with
|
||||
|
||||
```julia-repl
|
||||
julia> serve()
|
||||
→ Initial full pass...
|
||||
→ Starting the server...
|
||||
✓ LiveServer listening on http://localhost:8000/ ...
|
||||
(use CTRL+C to shut down)
|
||||
```
|
||||
|
||||
and navigate in a browser to the corresponding address to preview the website.
|
||||
|
||||
### Folder structure
|
||||
|
||||
The initial call to `newsite` generates a folder with the following structure:
|
||||
|
||||
```plaintext
|
||||
.
|
||||
├── _assets/
|
||||
├── _layout/
|
||||
├── _libs/
|
||||
├── config.md
|
||||
└── index.md
|
||||
```
|
||||
|
||||
After running `serve` the first time, an additional folder is generated: `__site` which will contain your full generated website.
|
||||
Among these folders:
|
||||
|
||||
@@tlist
|
||||
* the files in the top folder such as `index.md` are the source files for the generated pages, you must have an `index.md` or `index.html` at the top level but can then use whatever folder structure you want (see further),
|
||||
* you should **not** modify the content of `__site` as it's *generated* and any changes you do in there may be silently over-written whenever you modify files elsewhere,
|
||||
* the folders `_assets/`, `_libs/`, `_layout` and `_css` contain *auxiliary files* supporting your site:
|
||||
* `_assets/` will contain images, code snippets, etc.,
|
||||
* `_css/` will contain the style sheets,
|
||||
* `_libs/` will contain javascript libraries,
|
||||
* `_layout/` will contain bits of HTML scaffolding for the generated pages,
|
||||
@@
|
||||
|
||||
### Top folder
|
||||
|
||||
In this folder,
|
||||
|
||||
@@tlist
|
||||
* `index.md` will generate the site's landing page,
|
||||
* `pages/page1.md` would correspond to pages on your website (you can have whatever subfolder structure you want in here),
|
||||
* `config.md` allows to specify variables that help steer the page generation, you can also use it to declare global variables or definitions that can then be used on all pages.
|
||||
@@
|
||||
|
||||
\note{You can also write pages in plain HTML. For instance you may want to write an `index.html` file instead of generating it via the `index.md`. You will still need to put it at the exact same place and let Franklin copy the files appropriately.}
|
||||
|
||||
Note that Franklin generates a folder structure in `__site` which allows to have URLs like `[website]/page1/`. The following rules are applied:
|
||||
|
||||
* the filename is `[path/]index.md` or `[path/]index.html`, it will be copied over "as is" to `__site/[path/]index.html`,
|
||||
* the filename is `[path/]somepage.md` or `[path/]somepage.html`, it will be copied to `__site/[path/]somepage/index.html`.
|
||||
|
||||
So for instance if we ignore auxiliary files and you have
|
||||
|
||||
```
|
||||
.
|
||||
├── index.md
|
||||
├── folder
|
||||
│ └── subpage.md
|
||||
└── page.md
|
||||
```
|
||||
|
||||
it will lead to
|
||||
|
||||
```
|
||||
__site
|
||||
├── index.html
|
||||
├── folder
|
||||
│ └── subpage
|
||||
│ └── index.html
|
||||
└── page
|
||||
└── index.html
|
||||
```
|
||||
|
||||
which allows to have the following URLs:
|
||||
|
||||
@@tlist
|
||||
* `[website]/`
|
||||
* `[website]/page/`
|
||||
* `[website]/folder/subpage/`
|
||||
@@
|
||||
|
||||
### Reserved names
|
||||
|
||||
To avoid name clashes, refrain from using the following paths where `/` indicates the topdir (website folder):
|
||||
|
||||
@@tlist
|
||||
* `/css/` or `/css.md`
|
||||
* `/layout/` or `/layout.md`
|
||||
* `/literate/` or `/literate.md`
|
||||
@@
|
||||
|
||||
Also bear in mind that Franklin will ignore `README.md`, `LICENSE.md`, `Manifest.toml` and `Project.toml`.
|
||||
|
||||
### Editing and testing your website
|
||||
|
||||
The `serve` function can be used to launch a server which will track and render modifications.
|
||||
There are a few useful options you can use beyond the barebone `serve()`, do `?serve` in your REPL for all options, we list a few noteworthy one below:
|
||||
|
||||
@@tlist
|
||||
* `clear=false`, whether to erases `__site` and starts from a blank slate,
|
||||
* `single=false`, whether to do a single build pass generating all pages and not start the server.
|
||||
* `prerender=false`, whether to prerender code blocks and maths (see the [optimisation step](#optimisation_step))
|
||||
* `verb=false`, whether to show information about which page is being processed etc,
|
||||
* `silent=false`, whether to suppress any informative messages that could otherwise appear in your console when editing your site, this goes one step further than `verb=false` as it also applies for code evaluation,
|
||||
* `eval_all=false`, whether to re-evaluate all code blocks on all pages.
|
||||
@@
|
||||
|
||||
## Post-processing
|
||||
|
||||
### Verify links
|
||||
|
||||
Before deploying you may want to verify that links on your website lead somewhere, to do so use the `verify_links()`.
|
||||
It will take a few second to verify all links on every generated pages but can be quite helpful to identify dead links or links with typos:
|
||||
|
||||
```julia-repl
|
||||
julia> verify_links()
|
||||
Verifying links... [you seem online ✓]
|
||||
- internal link issue on page index.md: /menu3/.
|
||||
```
|
||||
|
||||
then after fixing and re-generating pages:
|
||||
|
||||
```julia-repl
|
||||
julia> verify_links()
|
||||
All internal and external links verified ✓.
|
||||
```
|
||||
|
||||
### Pre-rendering and compression
|
||||
|
||||
The `optimize` function can
|
||||
|
||||
@@tlist
|
||||
* pre-render KaTeX and highlight.js code to HTML so that the pages don't have to load these javascript libraries,
|
||||
* minify all generated HTML and CSS.
|
||||
@@
|
||||
See `?optimize` for options.
|
||||
|
||||
Those two steps may lead to faster loading pages.
|
||||
Note that in order to run them, you will need a couple of external dependencies as mentioned in the [installation section](/index.html#installing_optional_extras).
|
||||
|
||||
The `optimize` function is called by default in the `publish` function which can be used to help deploy your website.
|
||||
|
||||
### Publish
|
||||
|
||||
\note{If you use GitHub or GitLab with a deployment action on those platforms, you do not need to use `publish`, you can just push your changes and let the relevant action do the rest on the platform. See the section on [deployment](/workflow/deploy/).}
|
||||
|
||||
Once you have synched your local folder with a remote repository (see [deployment instructions](/workflow/deploy/)), the `publish` function can be called to deploy your website; it essentially:
|
||||
|
||||
@@tlist
|
||||
- applies an optional optimisation step (see previous point),
|
||||
- does a `git add -A; git commit -am "franklin-update"; git push`.
|
||||
@@
|
||||
|
||||
See `?publish` for more information.
|
||||
|
||||
In any case, before deploying, if you're working on a _project website_ i.e. a website whose root URL will look like `username.gitlab.io/project/` then you should add the following line in your `config.md` file:
|
||||
|
||||
```markdown
|
||||
@def prepath = "project"
|
||||
```
|
||||
|
||||
the `publish` function will then ensure that all links are fixed before deploying your website.
|
||||
|
||||
Note also that the `publish` function accepts a `final=` keyword to which you can pass any function `() -> nothing` to do some final post-processing before pushing updates online.
|
||||
For instance, you can use `final=lunr` where `lunr` is a function exported by Franklin which generates a Lunr search index (see [this tutorial](/extras/lunr/) for more details).
|
|
@ -1,73 +0,0 @@
|
|||
<!--
|
||||
reviewed: 18/4/20
|
||||
-->
|
||||
|
||||
# Page structure
|
||||
|
||||
|
||||
\blurb{Pages are assembled like lego blocks.}
|
||||
|
||||
<!-- \lineskip
|
||||
|
||||
\toc -->
|
||||
|
||||
## Overview
|
||||
|
||||
At a high level, the process to go from a markdown file `file.md` to the corresponding html page is quite simple:
|
||||
|
||||
```plaintext
|
||||
result = head * body * page_foot * foot
|
||||
```
|
||||
|
||||
where
|
||||
|
||||
* `head` corresponds to `_layout/head.html`,
|
||||
* `page_foot` and `foot` correspond respectively to `_layout/page_foot.html` and `_layout/foot.html`,
|
||||
* `body` correspond to Franklin's conversion of input markdown.
|
||||
|
||||
One additional step processes the resulting HTML to resolve any html function (`{{ ... }}`) that may be left.
|
||||
|
||||
The final HTML for a page will essentially look like:
|
||||
|
||||
```html
|
||||
<!-- head.html -->
|
||||
<!doctype html>
|
||||
<html>
|
||||
<head>
|
||||
...
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<!-- ...
|
||||
resolved body + page foot
|
||||
... -->
|
||||
|
||||
<!-- foot -->
|
||||
...
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Of course it will depend of what you have in your `_layout/head.html` etc, you can tweak this at will. You can also make this as modular as you want by using conditional blocks in your `head.html` and insert specific sub layouts depending on the page. For instance the `head.html` file could include something like
|
||||
|
||||
```html
|
||||
<!-- standard stuff -->
|
||||
{{ispage blog/*}} {{insert head_blog}}{{end}}
|
||||
<!-- ... -->
|
||||
```
|
||||
|
||||
for more on this, see the section on [page variables](/syntax/page-variables/).
|
||||
|
||||
\note{This also means that it is required to have a `_layout/head.html`, `_layout/foot.html` and `_layout/page_foot.html`, you **must** have these files but they can be empty (in practice it wouldn't make sense to have all of them be empty but you could have `page_foot` empty).}
|
||||
|
||||
### Resolved body
|
||||
|
||||
The resolved body is plugged in a "container" div
|
||||
|
||||
```html
|
||||
<div class="franklin-content">
|
||||
...
|
||||
</div>
|
||||
```
|
||||
|
||||
if you're using a CSS framework like bootstrap, you might want to control the name of that outer div which you can do by specifying `@def div_content = "container"` in your `config.md`.
|