Franklin Templates

Templates for Franklin, the static-site generator in Julia.

Most of these templates are adapted from existing, popular templates with minor modifications to accommodate Franklin's content.

NOTE: these templates should be seen as starting points, they are far from perfect. PRs to help improve them will be very welcome, thanks! Most importantly they are designed to be simple to adjust to your needs.

List of templates

Get an idea for which template you like using this preview. The grid below keeps track of their name, license, the kind of navbar they have and whether they require Javascript.

Name	Source	License	Navbar	JS
"sandbox"	N/A	MIT	N/A	No
"sandbox-extended"	N/A	MIT	N/A	No
"basic"	N/A	MIT	Top	No
"jemdoc"	jemdoc	N/A	Side	No
"hypertext"	grav theme hypertext	MIT	Top	No
"pure-sm"	pure css	Yahoo BSD	Side	No
"vela"	grav theme vela	MIT	Side (collapsable)	Yes
"tufte"	Tufte CSS, and a bit of Lawler.io for the menu	both MIT	Side	No
"hyde"	Hyde	MIT	Side	No
"lanyon"	Lanyon	MIT	Side (collapsable)	No
"just-the-docs"	Just the docs	MIT	Side/Top	No
"minimal-mistakes"	Minimal mistakes	MIT	Side/Top	No
"celeste"	Celeste	MIT	Top	No
"bootstrap5"	Bootstrap5	MIT	Top	No

Modifying or adding a template

The package contains a few utils to make it easier to modify or add templates. Now if it was just a bunch of fixes to an existing template, you can just push those changes to your fork and open a PR. If it's a new template that you're working on, you can also do that but there's a few extra things you need to do:

1. in FranklinTemplates/src/FranklinTemplates.jl add the name of your template in the list
2. in FranklinTemplates/docs/make.jl add the name of your template with a description in the list
3. in FranklinTemplates/docs/thumb add a screenshot of your template in png format with exactly an 850x850 dimension
4. in FranklinTemplates/docs/index_head.html add a CSS block following the other examples

To locally see changes quickly, use Changing a single template. To change all templates at the same time, use Changing multiple templates.

Changing a single template

1. clone a fork of this package wherever you usually do things, typically ~/.julia/dev/
2. checkout the package in development mode with ] dev FranklinTemplates
3. cd to a sensible workspace and do one of
   1. using FranklinTemplates; newsite("newTemplate") to start working on newTemplate more or less from scratch,
   2. using FranklinTemplates; newsite("newTemplate", template="jemdoc") to start working on newTemplate using some other template as starting point,
   3. using FranklinTemplates; modify("jemdoc") to quickly start working on an existing template in order to fix it.
4. change things, fix things, etc.
5. bring your changes into your fork with addtemplate("path/to/your/work")
   1. if the template doesn't exist, it will just add the folder removing things that are duplicate from templates/common/.
   2. if the template exists, it will just adjust what needs to be adjusted.

Changing multiple templates

1. clone a fork of this package wherever you usually do things, typically ~/.julia/dev/
2. checkout the package in development mode with ] dev FranklinTemplates
3. start serving the preview website with using FranklinTemplates; FranklinTemplates.serve_templates()

Thanks!!

Misc

• Current version of KaTeX: 0.16.0
• Current version of highlight: 11.5.1 (with css, C, C++, yaml, bash, ini,TOML, markdown, html,xml, r, julia, julia-repl, plaintext, python and the minified github theme).
• Current version of Plotly (used in sandbox-extended): 1.58.4

Notes

This package contains a copy of the relevant KaTeX files and highlight.js files;

• the KaTeX files are basically provided "as is", completely unmodified; you could download your own version of the files from the original repo and replace the files in _libs/katex,
• the Highlight.js files are essentially provided "as is" for a set of languages, there is a small modification in the highlight.pack.js file to highlight julia shell and pkg prompt (see next section). You can also download your own version of files from the original source where you might want to
  • specify languages you want to highlight if other than the default list above
  • specify the "style" (we use github but you could use another sheet)

Note: in Franklin's optimize pass, by default the full library highlight.js is called to pre-render highlighting; this bypasses the highlight.pack.js file and, in particular, supports highlighting for all languages. In other words, the highlight.pack.js file is relevant only when you preview your site locally with serve() or if you don't intend to apply the prerendering step.

Maintenance

• if update highlight.min.js, look for julia>, and replace with something like

{name:"Julia REPL",contains:[{className:"meta.prompt",begin:/^julia>/,relevance:10,starts:{end:/^(?![ ]{6})/,
subLanguage:"julia"}},{className:"meta.pkg",begin:/^\(.*\) pkg>/,relevance:10,starts:{end:/^(?![ ]{6})/,
subLanguage:"julia"}},{className:"meta.shell",begin:/^shell>/,relevance:10,starts:{end:/^(?![ ]{6})/,
subLanguage:"julia"}}],aliases:["jldoctest"]}

(copying the case for julia and adding a case for pkg and for shell, see also the CSS for .hljs-meta.pkg_ etc.)

• for testing all layouts jointly (you'll need to have PlotlyJS and Hyperscript installed)

Testing before release

include("docs/make.jl")
import LiveServer
LiveServer.serve(dir="docs/build")

• check that all templates have a thumbnail
• check that in basic - more goodies, the shell, pkg and julia prompts are highlighted properly (in case of update of highlight)
• check that math displays properly (in case of update of katex)