Serum

A simple static website generator


Two Changes are Coming

Monday, 22 May 2017 Tags: devnote serum

UPDATE: These changes are now merged to master branch. (May 26)

I recently have made two changes which adds flexibility to Serum’s functionalities. Those changes are not yet available on master branch, but they are still available on GitHub, on two separate branches. Let’s take a look at which changes are waiting for you!

1. Includes

A new kind of templates, called “includes” are added. Includes are special templates which are compiled and rendered as HTML stubs before any other regular templates are processed. Regular templates, such as templates/base.html.eex, templates/post.html.eex, …, can include these HTML stubs as much as you want.

Through this change, templates/nav.html.eex template, which represents the navigation area of your web page, has been dropped from a set of required templates. Now you don’t have to keep the file even if your site does not need the navigation area. If you need the navigation area, simply create a template under includes/ directory and include it from templates/base.html.eex or other regular template!

NOTE

It is not possible to define an include template which includes other include templates.

How to try this feature?

To try Serum with this feature enabled, fetch the latest commits from GitHub and checkout dev/includes branch. Be sure to clone the repository first if you don’t have one.

$ git fetch origin
$ git checkout dev/includes

Next, make sure all deps are satisfied and build the escript.

$ mix deps.get
$ mix escript.build --force

Now you can invoke ./serum to use Serum with “includes” feature.

Before actually use this version of Serum, you need to manually migrate templates in your projects first. Follow these instructions:

I don’t want a navigation area.

  1. Just delete the templates/nav.html.eex file.
  2. Open templates/*.html.eex with your favorite code editor and remove any occurrences of <%= navigation %>.

I want to keep the navigation area.

  1. Create a directory named includes right under your project root.
  2. Move templates/nav.html.eex to includes directory.
  3. Open templates/*.html.eex with your favorite code editor and replace all occurrences of <%= navigation %> with <%= include "nav" %>.

2. More flexible header

EDIT:

Header delimiter has been changed to ---.

So far, source files for pages and posts have required one or two lines of “header”, which defines the metadata of each page or post, at the very beginning of each file. The format of the header was very strict, and it was not ready for future changes, at all. So I decided to introduce a new syntax for metadata definition, which may look familiar for most of people. I hope it becomes easier for both Serum and the users to adapt to future changes well.

Before:

# This is the title
# some, tags

After:

===
title: This is the title
tags: some, tags
===

How to try this feature?

To try Serum with this feature enabled, fetch the latest commits from GitHub and checkout dev/flexible-header branch. Be sure to clone the repository first if you don’t have one.

$ git fetch origin
$ git checkout dev/flexible-header

Next, make sure all deps are satisfied and build the escript.

$ mix deps.get
$ mix escript.build --force

Now you can invoke ./serum to use Serum with “more flexible header” feature.

Before actually use this version of Serum, you need to manually migrate all files under pages/ and posts/ directory. Follow these instructions:

Migrating pages

Every source file under pages/ directory, whether *.md or *.html, should look like this:

# <Page Title Goes Here>

(Rest of the file ...)

Replace the first line like this:

===
title: <Page Title Goes Here>
===

(Rest of the file ...)

Migrating posts

Every source file under posts/ directory should look like this:

# <Post Title Goes Here>
# these, are, some, tags

(Rest of the file ...)

Replace the first two lines like this:

===
title: <Post Title Goes Here>
tags: these, are, some, tags
===

(Rest of the file ...)

If you want to leave a post untagged, just delete a line starting with tags:!

I wanna try both new features! How can I?

For those who want to preview these two changes at the same time, I prepared another branch named dev/changes-may-2017. Checkout this branch and follow the instructions described above. When you get a notification that these new features are now merged to master, just switch to master branch. Easy!

And while you are trying these new features, please feel free to open an issue any time you encounter a problem. All of your comments can make these features much better.

NOTE

The documentation will be updated after these branches are merged into master. In the meantime, if you have any questions regarding to these new features, please contact me through GitHub issue tracker or through email.