tlienart / Franklin.jl

Franklin: a Static Site Generator in Julia.

Franklin is a simple static site generator (SSG) oriented towards technical blogging (code, maths, ...), flexibility and extensibility. The base syntax is plain markdown with a few extensions such as the ability to define and use LaTeX-like commands in or outside of maths environments and the possibility to evaluate code blocks on the fly.

Franklin has a channel #franklin on the Julia slack, this is the best place to ask usage question.

Docs

Go to Franklin's main website. For users already familiar with Franklin you might also find these demos useful.

Some examples of websites using Franklin (if you're using Franklin with a public repo, consider adding the "franklin" tag to the repo to help others find examples, thanks!)

Adapted templates (i.e. starting from one of the available themes)

• Franklin's own website is written in Franklin, see docs/
• @cormullion's website, the author of Luxor.jl,
• MLJ's tutorial website which shows how Franklin can interact nicely with Literate.jl
• Tom Kwong's website author of Hands-on Design Patterns and Best Practices with Julia
• SymbolicUtils.jl's manual using the Tufte template
• @terasakisatoshi's website using the vela template, source
• @Wikunia's blog using the vela template
• SciML.ai, Julia's SciML Scientific Machine Learning organization website
• My website (by now a bit outdated... there's only so much one can do in a day)
• JuliaActuary, Julia's community promoting open-source actuarial science
• MIT Introduction to Computational Thinking course website
• Rik Huijzer's blog which is mostly about programming and statistics
• TuringModels implements the models from Statistical Rethinking using Turing.jl
• Ricardo Rosa's website source repo.

Custom templates (i.e. migrating an existing design)

• The Julia website, including the blog, are deployed using Franklin
• Circuitscape's website was migrated from Jekyll
• @zlatanvasovic's website using Bootstrap 4.5
• PkgPage.jl, front-page generator based on Franklin using Bootstrap 4.5
• @abhishalya's website using a custom minimalistic theme
• The JuliaCon website is deployed using Franklin

Key features

• Use standard markdown with the possibility to use LaTeX-style commands,
• Simple way to introduce div blocks allowing easy styling on a page (e.g. "Theorem" boxes etc.),
• Can execute and show the output of Julia code blocks,
• Simple optimisation step to accelerate webpage loading speed:
  • compression of HTML and CSS of the generated pages,
  • optional pre-rendering of KaTeX and highlighted code blocks to remove javascript dependency,
• Easy HTML templating to define or adapt a given layout.

See the docs for more information and examples.

Getting started

With Julia ≥ 1.3:

pkg> add Franklin

you can then get started with

julia> using Franklin

julia> newsite("MyNewSite")
✔ Website folder generated at "MyNewSite" (now the current directory).
→ Use serve() from Franklin to see the website in your browser.

julia> serve()
→ Initial full pass...
→ Starting the server...
✔ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

Modify the files in MyNewSite/src and see the changes being live-rendered in your browser. Head to the docs for more information.

You can also start from one of the templates by doing something like:

julia> newsite("MyNewSite", template="vela")

You might want to put the following command in your .bash_profile or .bashrc as a way to quickly launch the server from your terminal:

alias franklin=julia -O0 -e 'using Franklin; serve()'

Heads up!

While Franklin broadly supports standard Markdown there are a few things that may trip you which are either due to Franklin or due to Julia's Markdown library, here are key ones you should keep in mind:

• when writing a list, the content of the list item must be on a single line (no line break)
• you can write comments with <!-- comments --> the comment markers <!-- and --> must be separated by a character that is not a - to work properly so <!--A--> is ok but <!---A---> is not, best is to just systematically use a whitespace: <!-- A -->.
• be careful writing double braces, {{...}} has a meaning (html functions) this can cause issues in latex commands, if you have double braces in a latex command, make sure to add whitespaces for instance write \dfrac{1}{ {101}_{2} } instead of \dfrac{1}{{101}_{2}}. In general use whitespaces liberally to help the parser in math and latex commands.
• (as of v0.7) code blocks should be delimited with backticks ` you can also use indented blocks to delimit code blocks but you now have to opt in explicitly on pages that would use them by using @def indented_code = true, if you want to use that everywhere, write that in the config.md. Note that indented blocks are ambiguous with some of the other things that Franklin provides (div blocks, latex commands) and so if you use them, you are responsible for avoiding ambiguities (effectively that means not using indentation for anything else than code)

Associated repositories

• LiveServer.jl a package coded with Jonas Asprion to render and watch the content of a local folder in the browser.
• FranklinTemplates.jl the repositories where Franklin themes/templates are developed.

Licenses

Core:

• Franklin, FranklinTemplates and LiveServer are all MIT licensed.

External:

• KaTeX is MIT licensed,
• Node's is essentially MIT licensed,
• css-html-js-minify is LGPL licensed,
• highlight.js is BSD licensed.