Franklin Demos

Click here to see the source

This website is meant to be a quick way to show how to do stuff that people ask (or that I thought would be a nice demo), it will complement the official documentation.

It's not meant to be beautiful, rather just show how to get specific stuff done. If one block answers one of your question, make sure to check the source to see how it was done. The ordering is reverse chronological but just use the table of contents to guide you to whatever you might want to explore.

Note: an important philosophy here is that if you can write a Julia function that would produce the HTML you want, then write that function and let Franklin call it.

Note 2: the numbering in georgian script in the table of content is on purpose (though for no particularly good reason other than that it looks nice... 🇬🇪)

  1. (012) Dates
  2. (011) showing type information
  3. (010) clipboard button for code blocks
  4. (009) custom environment for TikzCD
  5. (008) (custom) environments and commands
    1. Customise with Julia code
  6. (007) delayed hfun
  7. (006) code highlighting
  8. (005) pagination
  9. (004) use Latexify.jl
  10. (003) styling of code output blocks
  11. (002) code block scope
  12. (001) how to load data from file and loop over rows
    1. Approach 1, with a hfun
    2. Approach 2, with a page variable and a for loop

(012) Dates

The date of last modification on the page is kept in the fd_mtime_raw internal page variable, there is also a pre-formatted fd_mtime.

Last modified: 2020-11-25 or November 25, 2020

(011) showing type information

This is a short demo following a discussion on Slack, it shows three things:

s = "hello"
struct T; v::Int; end
[
    Dict(:a => T(1)),
    Dict(:b => T(2)),
]
2-element Array{Dict{Symbol,T},1}:
 Dict(:a => T(1))
 Dict(:b => T(2))

Here's another cell

T(1)
print(s)
hello

Suppressed output:

X = randn(2, 3);

(010) clipboard button for code blocks

It's fairly easy to add a "copy" button to your code blocks using a tool like clipboard.js. In fact on this demo page, as you can see, there is a copy button on all code blocks. The steps to reproduce this are:

<script src="/libs/clipboard.min.js"></script>

and that's it 🏁.

(009) custom environment for TikzCD

Following up on #008, here's a custom environment for Tikz diagrams using the TikzCDs.jl package.

Let's first see what you get for your effort:

Cool! Modulo a div class that shrinks the image a bit, the code that was used here is very nearly a copy-paste from an example in the tikz-cd docs, the only difference is one additional bracket with the file name (here tcd1):

\begin{tikzcd}{tcd1}
A \arrow[r, "\phi"] \arrow[d, red]
  & B \arrow[d, "\psi" red] \\
  C \arrow[r, red, "\eta" blue]
  & D
\end{tikzcd}

The corresponding env_tikzcd function is in the utils.jl file and is quite simple.

Note: in this particular case, the environment uses the TikzCDs.jl which requires having lualatex and dvisgm as per their README. For this to work with a GitHub action, the relevant stuff needs to be installed, it's not hard to do so with GitHub actions though you need to get TeXLive 2019 to avoid errors, I used these 3 lines which you could copy.

(008) (custom) environments and commands

You can define new commands and new environments using essentially the same syntax as in LaTeX:

\newcommand{\command}[nargs]{def}
\newenvironment{environment}[nargs]{pre}{post}

The first one allows to define a command that you can call as \command{...} and the second one an environment that you can call as

\begin{environment}{...}...\end{environment}

In both cases you can have a number of arguments (or zero) and the output is reprocessed by Franklin (so treated as Franklin-markdown). Here are a few simple examples:

\newcommand{\hello}{**Hello!**}
Result: \hello.

Result: Hello!.

\newcommand{\html}[1]{~~~#1~~~}
\newcommand{\red}[1]{\html{<span style="color:red">#1</span>}}
Result: \red{hello!}.

Result: hello!.

\newenvironment{center}{
  \html{<div style="text-align:center">}
}{
  \html{</div>}
}
Result: \begin{center}This bit of text is in a centered div.\end{center}

Result:

This bit of text is centered.
\newenvironment{figure}[1]{
  \html{<figure>}
}{
  \html{<figcaption>#1</figcaption></figure>}
}
Result: \begin{figure}{A koala eating a leaf.}![](/assets/koala.jpg)\end{figure}

Result:

A koala eating a leaf.

Customise with Julia code

Much like hfun_*, you can have commands and environments be effectively defined via Julia code. The main difference is that the output will be treated as Franklin-markdown and so will be reprocessed by Franklin (where for a hfun, the output is plugged in directly as HTML).

In both cases, a single option bracket is expected, no more no less. It can be empty but it has to be there. See also the docs for more information.

Here are two simple examples (see in utils.jl too):

function lx_capa(com, _)
  # this first line extracts the content of the brace
  content = Franklin.content(com.braces[1])
  output = replace(content, "a" => "A")
  return "**$output**"
end
Result: \capa{Baba Yaga}.

Result: BAbA YAgA.

function env_cap(com, _)
  option = Franklin.content(com.braces[1])
  content = Franklin.content(com)
  output = replace(content, option => uppercase(option))
  return "~~~<b>~~~$output~~~</b>~~~"
end
Result: \begin{cap}{ba}Baba Yaga with a baseball bat\end{cap}

Result:

BaBA Yaga with a BAseBAll BAt

Of course these are toy examples and you could have arrived to the same effect some other way. With a bit of practice, you might develop a preference towards using one out of the three options: hfun_*, lx_* or env_* depending on your context.

(007) delayed hfun

When you call serve(), Franklin first does a full pass which builds all your pages and then waits for changes to happen in a given page before updating that page. If you have a page A and a page B and that the page A calls a function which would need something that will only be defined once B is built, you have two cases:

  1. A common one is to have the function used by A require a local page variable defined on B; in that case just use pagevar(...). When called, it will itself build B so that it can access the page variable defined on B. This is usually all you need.

  2. A less common one is to have the function used by A require a global page variable such as, for instance, the list of all tags, which is only complete once all pages have been built. In that case the function to be used by A should be marked with @delay hfun_...(...) so that Franklin knows it has to wait for the full pass to be completed before re-building A now being sure that it will have access to the proper scope.

The page foo has a tag foo and a page variable var; let's show both use cases; see utils.jl to see the definition of the relevant functions.

Case 1 (local page variable access, var = 5 on page foo):

var read from foo is 5

Case 2 (wait for full build, there's a tag index here and a tag foo on page foo):

tags: { index foo }

(006) code highlighting

Inserting highlighted code is very easy in Franklin; just use triple backquotes and the name of the language:

struct Point{T}
  x::T
  y::T
end

The highlighting is done via highlight.js, it's important to understand there are two modes:

The first one only has support for selected languages (by default: css, C/AL, C++, yaml, bash, ini, TOML, markdown, html, xml, r, julia, julia-repl, plaintext, python with the minified github theme), you can change this by going to the highlightjs and making your selection.

The recommendation is to:

Here are some more examples with languages that are in the default list:

# some R
a <- 10
while (a > 4) {
  cat(a, "...", sep = "")
  a <- a - 1
}
# some Python
def foo():
  print("Hello world!")
  return
// some c++
#include <iostream>

int main() {
  std::cout << "Hello World!";
  return 0;
}
/* some CSS */
p {
  border-style: solid;
  border-right-color: #ff0000;
}

(005) pagination

Pagination works with {{paginate list num}} where list is a page variable with elements that you want to paginate (either a list or tuple), and num is the number of elements you want per page. There are many ways you can use this, one possible way is to wrap it in a command if you want to insert this in an actual list which is what is demoed here:

Now observe that

(004) use Latexify.jl

Latexify produces a LaTeX string which should basically be passed to KaTeX. To do that you need to recuperate the output, extract the string and pass it into a maths block.

Here there's a bug with \begin{equation} in Franklin (issue #584) which is why I'm replacing those with $$ but it should be fixed in the near future so that you wouldn't have to use these two "replace" lines:

using Latexify
empty_ary = Array{Float32, 2}(undef, 2, 2)
ls = latexify(empty_ary) # this is an L string
\[ \left[ \begin{array}{cc} 1.53e-43 & -5.8026476e9 \\ 0.0 & 4.5647e-41 \\ \end{array} \right] \]

(003) styling of code output blocks

At the moment (August 2020) no particular class is added on an output (see #531); you can still do something similar by adding a @@code-output (or whatever appropriate name) around the command that extracts the output and specify this in your css (see extras.css):

x = 7
7

If you find yourself writing that a lot, you should probably define a command like

\newcommand{\prettyshow}[1]{@@code-output \show{#1} @@}

and put it in your config.md file so that it's globally available.

7

(002) code block scope

On a single page all code blocks share their environment so

x = 5

then

y = x+2
7

(001) how to load data from file and loop over rows

This was asked on Slack with the hope it could mimick the Data Files functionality of Jekyll where you would have a file like

name,github
Eric Mill,konklone
Parker Moore,parkr
Liu Fengyun,liufengyun

and you'd want to loop over that and do something with it.

Relevant pieces:

Approach 1, with a hfun

Approach 2, with a page variable and a for loop

Writing the following

~~~
<ul>
{{for (name, alias) in members_from_csv}}
  <li>
    <a href="https://github.com/{{alias}}">{{name}}</a>
  </li>
{{end}}
</ul>
~~~

gives:

Notes: