How to use Franklin
This section is meant as a refresher if you're new to Franklin. Have a look at both how the website renders and the corresponding markdown (index.md
). Modify at will to get a feeling for how things work!
Ps: if you want to modify the header or footer or the general look of the website, adjust the files in
src/_css/
andsrc/_html_parts/
.
The base with Markdown
The standard markdown syntax can be used such as titles using #
, lists:
element with bold
element with emph
or code-blocks inline
or with highlighting (note the @def hascode = true
in the source to allow highlight.js to do its job):
abstract type Point end
struct PointR2{T<:Real} <: Point
x::T
y::T
end
struct PointR3{T<:Real} <: Point
x::T
y::T
z::T
end
function len(p::T) where T<:Point
sqrt(sum(getfield(p, η)^2 for η ∈ fieldnames(T)))
end
You can also quote stuff
You must have chaos within you to ...
or have tables:
English | Mandarin |
---|---|
winnie the pooh | 维尼熊 |
Note that you may have to do a bit of CSS-styling to get these elements to look the way you want them (the same holds for the whole page in fact).
Symbols and html entities
If you want a dollar sign you have to escape it like so: $, you can also use html entities like so: → or π or, if you're using Juno for instance, you can use \pi[TAB]
to insert the symbol as is: π (it will be converted to a html entity).[1]
If you want to show a backslash, just use it like so: \ ; if you want to force a line break, use a \\
like
so (this is on a new line).[2]
If you want to show a backtick, escape it like so: ` and if you want to show a tick in inline code use double backticks like so ` ...
.
Footnotes are nice too:
[1] | this is the text for the first footnote, you can style all this looking at .fndef elements; note that the whole footnote definition is expected to be on the same line. |
[2] | and this is a longer footnote with some blah from veggie ipsum: turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus winter purslane kale. Celery potato scallion desert raisin horseradish spinach carrot soko. |
Basic Franklin extensions
Divs
It is sometimes useful to have a short way to make a part of the page belong to a div so that it can be styled separately. You can do this easily with Franklin by using @@divname ... @@
. For instance, you could want a blue background behind some text.
Since it's just a <div>
block, you can put this construction wherever you like and locally style your text.
LaTeX and Maths
Essentially three things are imitated from LaTeX
you can introduce definitions using
\newcommand
you can use hyper-references with
\eqref
,\cite
, ...you can show nice maths (via KaTeX)
The definitions can be introduced in the page or in the config.md
(in which case they're available everywhere as opposed to just in that page). For instance, the commands \scal
and \R
are defined in the config file (see src/config.md
) and can directly be used whereas the command \E
is defined below (and therefore only available on this page):
Now we can write something like
since we've given it the label \label{equation blah}
, we can refer it like so: (1) which can be convenient for pages that are math-heavy.
In a similar vein you can cite references that would be at the bottom of the page: (Noether (1915), Bezanson et al. (2017)).
Note: the LaTeX commands you define can also incorporate standard markdown (though not in a math environment) so for instance let's define a silly \bolditalic
command.
and use it here for example.
Here's another quick one, a command to change the color:
This is in blue or in #bf37bc.
A quick note on whitespaces
For most commands you will use #k
to refer to the -th argument as in LaTeX. In order to reduce headaches, this forcibly introduces a whitespace on the left of whatever is inserted which, usually, changes nothing visible (e.g. in a math settings). However there may be situations where you do not want this to happen and you know that the insertion will not clash with anything else. In that case, you should simply use !#k
which will not introduce that whitespace. It's probably easier to see this in action:
with:
/usr/local/bin/ script.jl
, there's a whitespace you don't want 🚫without:
/usr/local/bin/script.jl
here there isn't ✅
Raw HTML
You can include raw HTML by just surrounding a block with ~~~
. Not much more to add. This may be useful for local custom layouts like having a photo next to a text in a specific way.
Marine iguanas are truly splendid creatures. They're found on the Gálapagos islands, have skin that basically acts as a solar panel, can swim and may have the ability to adapt their body size depending on whether there's food or not.
Evolution is cool.
Note 1: again, entire such blocks can be made into latex-like commands via \newcommand{\mynewblock}[1]{...}
.
Note 2: whatever is in a raw HTML block is not further processed (so you can't have LaTeX in there for instance). A partial way around this is to use @@...
blocks which will be recursively parsed. The following code gives the same result as above with the small difference that there is LaTeX being processed in the inner div.
Marine iguanas are truly splendid creatures. They're not found in equations like . But they're still quite cool.
Pages and structure
Here are a few empty pages connecting to the menu links to show where files can go and the resulting paths. (It's probably best if you look at the source folder for this).
References (not really)
Bezanson, Edelman, Karpinski and Shah, Julia: a fresh approach to numerical computing, SIAM review 2017.
Header and Footer
As you can see here at the bottom of the page, there is a footer which you may want on all pages but for instance you may want the date of last modification to be displayed. In a fashion heavily inspired by Hugo, you can write things like
Last modified: {{ fill fd_mtime }}.
(cf. src/_html_parts/page_foot.html
) which will then replace these braces with the content of a dictionary of variables at the key fd_mtime
. This dictionary of variables is accessed locally by pages through @def varname = value
and globally through the config.md
page via the same syntax.
There's a few other such functions of the form {{fname p₁ p₂}}
as well as support for conditional blocks. If you wander through the src/_html_parts/
folder and its content, you should be able to see those in action.