Serum

A simple static website generator


Back to the index

Templates

Serum provides four templates you need to define under the templates directory. Each template file is an Embedded Elixir(EEx) files. Please read the official EEx documentation for more information about EEx.

Global Variables

These are variables you can use in any template files.

site_name

<%= site_name %>

Returns the name of the website, which are specified in serum.json file.

site_description

<%= site_description %>

Returns the description (or subtitle) of the website, which are specified in serum.json file.

author

<%= author %>

Returns the value of author field in serum.json file.

author_email

<%= author_email %>

Returns the email address of website author specified in serum.json file.

pages

<%= for p <- pages do %>
  ...
<% end %>

Returns the list of all pages in the website. This can be useful when you make a navigation area or an index page. Each item in this list is a page object.

Refer to the Objects Reference to learn more about page objects.

posts

<%= for p <- posts do %>
  ...
<% end %>

Returns the list of all blog posts, sorted by date in descending order. You can use this if you want to make another post listings, besides the auto-generated ones. Each item in this list is a post object.

Refer to the Objects Reference to learn more about post objects.

tags

<%= for p <- tags do %>
  ...
<% end %>

Returns the list of all tags existing in the website. Each item in this list is a tuple with two elements {tag, count}, where tag is a tag object and count is the number of blog posts which have this tag.

Refer to the Objects Reference to learn more about tag objects.

Helper Macros

There are some helper macros for use in templates. You will need to utilize these macros to make templates that really work.

base/0 and base/1

<%= base() %>
<!-- ==> /base/url/ -->
<%= base "assets/css/style.css" %>
<!-- ==> /base/url/assets/css/style.css -->

Prepends the base URL in front of the specified path.

This is the most basic way to reference files and path, but it’s more recommended to use the other helper macros below whenever possible, as each of those macros does more specific jobs. This function should be used only when all of the other helpers don’t satisfy your needs.

page/1

<%= page "getting-started" %>
<!-- ==> /base/url/getting-started.html -->
<%= page "docs/index" %>
<!-- ==> /base/url/docs/index.html -->
<%= page "docs/" %>
<!-- ==> /base/url/docs/.html (may be an undesired output) -->

This is a shortcut macro for accessing pages. Please note that you should not put .html at the end of the path, and passing a directory as an argument produces a wrong output.

post/1

<%= post "2016-11-20-1937-some-post" %>
<!-- ==> /base/url/posts/2016-11-20-1937-some-post.html -->

This shortcut macro helps accessing blog posts. Like page/1, you should not append .html to the name of a post.

asset/1

<%= asset "js/script.js" %>
<!-- ==> /base/url/assets/js/script.js -->

Use this macro whenever you need to reference an asset. Calling asset("path") is equivalent to calling base("/base/url/assets/path").

NOTE

You may have noticed that there is no helper macro for accessing media files. This is intended because media files are supposed to be used in some pages or blog posts. You can, still, access those files by using base/1 macro, but in that case you really need to consider moving those files into assets/ directory.

include/1

See Includable Templates.

List of Required Templates

Below is the list of all five templates you need to define, with brief illustrations showing the role of each template and what functions or variables can be used.

templates/base.html.eex

<%= page_title %>Site Header<%= site_name %><%= site_description %>Main Contents Area<%= contents %>Site Footer

This template defines the overall structure and look & feel of the website. In other words, the root element of the page (<html></html>) should be defined here.

In addition to common helper functions, you need to use the additional variables specific to this template, which are:

  • page_title

    The text displayed in the title bar of the web browser. This is usually expanded into the title of a page or a blog post.

  • contents

    Represents the main contents area. Depending on the type of the page, it’s replaced by the rendered result of page.html.eex, list.html.eex, or post.html.eex.

templates/page.html.eex

Site HeaderGlobal Navigation AreaMain Contents Area<%= contents %>Site Footer

This template does only one job: Wrapping the contents of a page. When building a page, the HTML converted from a markdown file will be wrapped by this template, and the wrapped contents will finally be wrapped again, by base.html.eex.

templates/list.html.eex

Site HeaderGlobal Navigation AreaMain Contents Area<%= header %><%= for p <- posts do %>...<% end %>Site Footer

Defines the appearance of the blog post list. Place these variables in appropriate position:

  • header

    The title text of the list page such as “All Posts” or “Posts tagged …”. You can set the format of this text in serum.json.

  • posts

    A list of post objects, sorted by date in descending order. Read Objects Reference for more information about post objects. This list may contain all posts in the website, or some posts filtered by a tag.

templates/post.html.eex

Site HeaderGlobal Navigation AreaMain Contents Area<%= title %><%= date %><%= for t <- tags do %> ... <% end %><%= contents %>Site Footer

This template formats blog post pages. Use these variables in appropriate places:

  • title

    The title of this blog post.

  • date

    The string representation of date when this post has been written.

  • raw_date

    A nested tuple of integers representing the date of the post, in the form of {{year, month, day}, {hours, minutes, 0}}.

  • tags

    A list of tag objects. Please see Objects Reference for more information about tag objects.

  • contents

    The HTML code converted from the source markdown file.