Serum

A simple static website generator


Serum Now Uses 2-Pass Approach

Sunday, 21 May 2017 Tags: devnote serum

For a recent few days, I have worked on changing Serum’s internal behavior on a different branch, and this branch was finally merged to master. Now Serum builds projects through 2-pass procedure!

Until now, Serum has built projects in a single pass like this:

  • Preparation

    • Load and compile templates
    • Compile nav area (*)
  • Page Builder

    • Scan for page source files
    • Collect page information
    • Render each page into HTML
  • Post Builder

    • Scan for post source files
    • Collect post information
    • Render each post into HTML
  • Index Builder

    • Generate tags information
    • Generate(Render) post listings
  • Finishing touch, cleanup, …

    • Copy assets and media (if any)

This procedure is simple, and is working great. The website you are looking at right now is also made through this steps. However, this 1-pass approach has some drawbacks. What if you want to put information about the latest blog post in the “sidebar” area? How can you automatically populate the navigation area based on a list of existing pages in the website? You can not. In order to do so, you need to give the templates instructions to utilize page(or post) information, but these templates must be already compiled before Serum starts rendering any pages, blog posts or post listings. And it is obvious that templates don’t know anything about pages or posts at that moment.

To make an opportunity to resolve these problems, I splitted some procedures into two passes:

  • Page Builder (Pass 1)

    • Scan for page source files
    • Collect page information
  • Post Builder (Pass 1)

    • Scan for post source files
    • Collect post information
  • Template Loader

    • Load and compile templates
    • Compile nav area (*)
  • Page Builder (Pass 2)

    • Render each page into HTML
  • Post Builder (Pass 2)

    • Render each page into HTML
  • Index Builder

    • Generate tags information
    • Generate(Render) post listings
  • Finishing touch, cleanup, …

    • Copy assets and media (if any)

If you are using the latest snapshot(commit) of Serum, you are already building your website with 2-pass-enabled Serum! As I said at the beginning of this post, all that changed is only the internal behavior of Serum. So you may not notice any changes but slightly increased build time. But now it became much easier for me to implement new features which can help you make richer static website. So keep an eye on this blog for new updates!

Footnote

(*) The template for the navigation area (templates/nav.html.eex) will be moved to includes directory sooner or later. This is the new feature which adds some flexibility in using EEx templates.