Page variables

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,... any Julia value. 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"""

You can also define them in blocks surrounded by +++ on a new line. The content between the +++ markers will then be evaluated as Julia code and all assigned variables will be considered as page variables. For instance, consider:

+++
var1 = [1, 2,
  3, 4]
var2 = "Hello goodbye"
+++

this block will be executed as standard Julia code and the two assignments (var1 and var2) will be caught and made available as page variables of the same name.

Page variables can serve multiple purposes though their main use is to be accessed from the HTML template blocks e.g.:

<footer>
  This is the footer. &copy; {{fill author}}.
</footer>

which could be useful as a footer on all pages.

The syntax {{ ... }} indicates an 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 and Global

Local page variables denote variables that are defined on one page and directly accessible on that page. Global page variables, by contrast, are directly available on all pages. Any variable defined in your config.md file is global.

In both cases, there are default page variables set by Franklin with default values which you can both change and use. You can of course also define your own variables, both global and local.

Defining and accessing page variables

Let us say that in config.md, we have

@def global_var_1 = "foo"

and that in index.md, we have

@def local_var_1 = "bar"

On index.md, you can access both variables so this:

{{global_var_1}} - {{local_var_1}}

will insert

foo - bar

On another page (say other.md), only global_var_1 is directly accessible but you can still access local_var_1 except you have to specify where it's defined (and you must use fill to do so):

{{global_var_1}} - {{fill local_var_1 index.md}}

The second bit says: "get local_var_1 from index.md".

Using page variables

Both local and global page variables are meant for essentially two purposes:

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 *.htmland .md files; in particular, they can be used 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:

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:

{{if hasmath}} {{insert head_katex.html}} {{end}}

the conditional blocks are explained below.

Conditional blocks

Conditional blocks allow specifying which parts of the HTML template should be active depending on the value of the given page variable(s). The format follows this structure:

{{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.

You can also use some dedicated conditional blocks:

The {{ispage ...}} and {{isnotpage ...}} accept * as joker symbol; for instance {{ispage maths/*}} is allowed.

Note: for people used to C syntax, you can also use ifdef, ifndef.

Consider the following example (very similar to what is used on the current page):

<li class="{{ispage syntax/*}}active{{end}}">• Syntax
<ul>
  <!-- ... -->
  <li class="{{ispage syntax/page-variables}}active{{end}}">Page Variables
  <!-- ... -->
</ul>

This is a simple 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:

{{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

{{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).

Notes:
(*) 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"
(**) 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.
(***) 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/". Always ignored are .DS_Store, .gitignore, LICENSE.md, README.md, franklin, franklin.pub, and node_modules/ (see IGNORE_FILES).

Other global settings

Those are less relevant global settings that you could modify but typically shouldn't.

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:

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

Notes:
(*) if the title is not set, the first header will be used as title.
(**) there may be cases where you want to literally type ]: in some code without it indicating a link reference. In such a case, set reflinks to false to avoid ambiguities.
(***) 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 information on these, see the section on inserting and evaluating code.