Serum

A simple static website generator


New Stuff So Far

Thursday, 24 Aug 2017 Tags: devnote serum

This post lists new features and changes introduced so far since the last post.

Detailed Help Text

Now the Serum command line program displays more detailed help texts for each task. If serum help is run without any argument, the program will print a list of available tasks:

output of "serum help"

And, for example, if you run serum help build, it will print a detailed documentation about the build task:

output of "serum help"

The program uses undocumented IO.ANSI.Docs built-in module to display the help texts for now. This module is internally used in IEx sessions for displaying documentations.

Exit Codes

This is also about the Serum command line program. Until now, the program always returned exit status of 0 no matter how the task ended, except that it crashes. But now it returns three different exit code depending on the result of the task:

  • 0: The task ended successfully (Some warnings might have been emitted).
  • 1: An error occurred while running the given task.
  • 2: There is a problem in the command line argument.

Your Templates Can Do More

Three new variables became available for use in EEx any templates: pages, posts and tags. These are lists of pages, blog posts and tags respectively.

Also, I recently added support for EEx pages. And guess what, you can use all of template variables and helper macros in your EEx pages! These two changes may significantly improve flexibility of your website structure. For example, only templates/list.html.eex could contain a list of blog posts so far. But now you can make the front page (i.e. index.html) to have a list of recent 5 posts, and a lot more!

pages/index.html.eex:

---
metadata ...
---

<h1>Welcome to my website!</h1>
<p>Lorem ipsum dolor sit amet, ...</p>

<h2>Recent Posts</h2>
<ul>
  <%= for post <- Enum.take(posts, 5) do %>
    <!-- Posts are sorted by date in decending order. -->
    <li><%= post.title %></li>
  <% end %>
</ul>

For right now, “EEx pages” feature only supports HTML output. But someday you may be able to use *.md.eex too.

Post Date

Serum no longer parses file names in /path/to/project/posts directory to extract date information. Instead, you need to specify post date in the header area. This means that you can now give whatever name you want to your post source file.

posts/0001-test-post.md:

---
title: Test Post
date: 2017-08-24 21:02:00
tags: serum, test, dev
---

The quick brown fox jumps over the lazy dog ...

Looking at the third line, you can see you need to specify the date in YYYY-MM-DD hh:mm:ss format.

Additional Metadata for Your Pages

Three new metadata keys have been added: label, group and order. These metadata can be useful when you are building the global navigation or some index pages. Since the detailed explanation of these metadata can be found here, let’s jump right into the real examples.

Suppose that you have some pages listed below:

filetitlelabelgrouporder
index.htmlWelcomeHomemain-nav10
contacts.mdContact MeContactsmain-nav90
works/index.html.eexMy WorksWorksmain-nav25
works/projects.mdMy Projectsworks1
works/collaborations.mdMy Collaborationsworks2
profile.mdAbout MeProfilemain-nav20

And you need to make the navigation area with EEx template. Then you could write the code like this:

includes/nav.html.eex:

<ul>
  <%= for page <- pages, page.group == "main-nav" do %>
    <li><a href="<%= page.url %>"><%= page.label %></a></li>
  <% end %>
</ul>

These new metadata work well with templates. All item in pages list is sorted by the value of order in ascending order. So the rendered result may look like this:

<ul>
    <li><a href="/my-site/index.html">Home</a></li>
    <li><a href="/my-site/profile.html">Profile</a></li>
    <li><a href="/my-site/works/index.html">Works</a></li>
    <li><a href="/my-site/contacts.html">Contacts</a></li>
</ul>

That’s it!

Lots of things have been added and changed for a last few months, and I’m glad to finally announce these changes. If you have any comments or great ideas, feel free to share your words with us!