Page Variables (part 1)

Overview

The main purpose of page variables is to communicate informations to the HTML layout from the page content. However, once you get the hang of it, you might decide to use them for quite a bit more than that.

As a first example, let's say that you would like the layout of your blog pages to include an author blurb at the bottom. This could be some fixed HTML structure with different information for each page (e.g.: different author name, bio, path for mugshot, ...).

In Franklin you can indicate this in the layout with something like:

<div class="author-card">
  <div class="author-name">{{author_name}}</div>
  <div class="author-blurb">{{author_blurb}}</div>
  <div class="author-mug">
    <img src="{{author_mug_src}}" alt="{{author_name}}"/>
  </div>
</div>

The {{author_name}} syntax means "insert the content of the author_name page variable here". Page variables can be defined in the Markdown of a page inside a block fenced with '+++':

+++
author_name  = "Emmy Noether"
author_blurb = """
  German mathematician who made many important
  contributions to abstract algebra.
  """
author_mug = "/assets/emmy.png"
+++

This might already give you a good idea but let's dive into the specifics.

Page variables basics

Assignment

Page variables can be defined on any page in a dedicated block fenced with '+++'. We'll call such a block a def-block from now on. What is placed inside that block must be valid Julia code and will be evaluated as such, all assignments will be extracted.

There can be multiple such blocks anywhere on a page though, typically, there will only be one, at the top. Here's an example where we define two page variables a and b, page variables can be accessed from within the Markdown itself or in the HTML layout:

+++
a = 5
b = "hello"
+++

Rest of the markdown, we can also expose variables here:
* `a`: {{a}}
* `b`: {{b}}

Since the content of the def-block is evaluated as Julia code, you can load packages and use code to define variables:

+++
using Dates
todays_date = Dates.today()
+++

Build-date: {{todays_date}}.

Usage

Page variables can be used with the following syntax:

{{name_of_function name_of_var_1 ...}}

The case {{name_of_var}} is a shortcut for {{fill name_of_var}}. Note that if there is a clash between the name of a var and the name of a function, the function will be called with priority.

The functions called in such a way are called HTML-functions or hfuns for short and can have zero or more arguments. There are several core functions like fill and you can define your own as we will show further.

When inserting a page variable with {{var_name}} or {{fill var_name}}, the Julia function repr will be called on the value of var_name and that is what will effectively be included. For basic Julia types (Int, Bool, ...), this will typically look like what you would expect but for custom types that you would have defined or that are defined in a package, you would have to consider what repr(obj) returns. For types in AbstractString, repr(obj) adds quotation marks which are stripped.

+++
a = true
b = [1,2,3]
c = Dict(:a => 5, :b => 7)
+++

* a: {{a}}
* b: {{b}}
* c: {{c}}

Local and global contexts

In a Franklin session there is a global (site-wide) context and a set of local (page-related) contexts which are attached to it. Page variables can be assigned at both levels. You have already seen how to do so at a page-level by just adding a +++...+++ block in the corresponding Markdown, you can do the same at global-level by adding such a block in your config.md file.

Variables defined at global-level are accessible from anywhere whereas variables defined at local-level are only directly accessible from the page on which they are defined (see also the next point). When a variable is defined at both levels, the local one takes precedence.

Accessing variables defined on another page

You can fill the content of a page variable defined on another page with

{{fill var_name relative_path}}

where the relative_path indicates the relative path to the page which defines var_name.

For instance both the current page and /syntax/basics.md define a variable header:

* by default we fill from the local page: **{{header}}** (or **{{fill header}}**)
* but we can query a specific page: **{{fill header syntax/basics}}**

The path is relative to the website folder. You can add a / at the start and a .md at the end but it's not required.

Updating page variables

When a local or global page variable is updated, any page that refers to it will be re-built so that the full website takes the new definition into account.

To help keep this process simple and fast, there are two constraints in how you can use page variables:

1. do not have references of depth more than 1 (i.e. a page variable can be defined by a reference to another page variable but no more depth than that)
2. avoid using page variables in executed code blocks.

Default variables

Franklin defines a number of page variables with default values that you can use and overwrite. You don't have to use or set any of those unless you find one useful.

Local variables

The slug variable allows you to specify an explicit secondary output location for the page. For instance if you're currently working on a page a/b/c.md, the default output path will be such that the relevant page can be addressed at /a/b/c/. However if you specify slug = "c/d" then that page will also be available at /c/d/. You can also specify a path with a .html extension in which case exactly that path will be used:

• slug = "c/d" → the page will also be available at /c/d/
• slug = "c/d.html" → the page will also be available at /c/d.html

For more on the topic you might want to read about default paths in Franklin. Check also the keep_path global variable in the next section.

Global variables

Just as with default local variables, you might find it useful to access or set some of those though many might be irrelevant for you.

Same as for local variables, there is a set of default global variables that are used by Franklin and which you should, generally, not set yourself though you might want to access them.

For legacy purposes, a number of these variables have aliases: