An Elmstatic Experience • CANENA

Update 2023-02-23

Note that this site no longer employs elmstatic, it's a great project nontheless so the rest of the article stays as is.

A quick walkthrough of how I migrated this site to use Elmstatic instead of my buggy, hand-made Elm-to-static-HTML script.

Iterate, Adapt, Repeat

Originally the blog started out using plain HTML/CSS employing a rather strict BEM approach. As I got more into Elm at the time I decided it would be a fun exercise to use it to create the markup and elm-static-html-lib seemed like a good choice. And so I hacked away at a Node script that produced the desired artifacts out of an Elm/Markdown mixture; the outcome certainly wasn’t something to be proud of. It was pretty buggy and annoying to work with, to be honest, but being able to leverage Elm for the layout stuff and writing content in Markdown was still the big plus I hoped for, so I didn’t roll back. I did wait for official server-side-rendering support that seemed to be on the horizon at that time.

Enter Elmstatic

However, as it became clear that official support for server-side-rendering would be put on hold when 0.19 was released and elm-static-html-lib didn’t receive an upgrade to the new language version I started to look for alternatives. Since users were now barred from (ab-)using never published-as-an-API Native modules many workable approaches in Elm 0.18 seized to be an option, short of forking the Elm compiler - probably for the better. So I ultimately opted for Elmstatic instead of rolling my own because the setup is essentially the same I had thought of earlier:

No dynamic content creation needed so use a static site generator
Keep on relying on Markdown for content
Continue to use Elm for most of the layout structure and styling
Use JSDOM to run the Elm app to produce the final markup
Reduce NPM dependencies as much as possible

On top of that the usage is so straight forward, it is a delight

npm install --save-dev elm@elm0.19.0 elmstatic && npx elmstatic init
# do your thing
npx elmstatic

Content Migration

Most of my posts are pretty basic and didn’t really need any adjustment apart from moving the post metadata from my custom Elm structure into the markdown frontmatter.

meta =
  { date = Date.date 2019 3 4
  , route = Article Blog_2019_03_04_typescript_vs_the_real_world
  , tags =
    [ Elm
    , Tech
    , Web
    ]
  , title = "TypeScript vs the Real World"
  }

became

---
title: TypeScript vs the Real World
tags: elm tech web
---

Note that Elmstatic takes care of the date and routing stuff for you, just name the file according to YYYY-MM-DD-your-url-safe-title and you’re good to go.

Layout Migration

To my surprise I didn’t even hit a bump when I migrated my Hello Living Styleguide post that demonstrated the BEM blocks used for the layout. Due to the mild namespacing of the BEM styles to a .ui-theme that I’d always found useful it was pretty easy to include the old styles inside a custom Elmstatic layout and have them applied only to the content sub-tree of the document without disturbing the new styling. Very nice!

<html class="ui-layout">
...
<body>
  ...
  <link rel="stylesheet" href="oldstyles.css">
  <div class="ui-theme">
    <!-- BEM styles only apply here -->
  </div>
</body>
</html>

As I had no intention of continuing to use my hopelessly over-engineered BEM CSS styles I just adapted the elm-css global styles that came with the scaffold. I might come back to that and do some cleanup in the future now that that it’s backed by Elm instead of less.

Lessons Learned Along the Road

The migration turned out to be very straight forward but as always there were some minor annoyances.

No Typed Routes

I did lose one feature along the way in that my custom script supported extracting routes and tags from Elm Custom Types with the help of some dark regex magic so Elm would complain when I got a route wrong, no big deal.

Static Deployment is can be easy

Not a problem with Elmstatic but after realizing that user/org pages on Github need to be served from / in master I scrapped my deploy-to-docs-directory strategy and moved all the source files into the src directory and had the build-step copy the built artifacts into the repository root. Et vóila, it works!

Yarn Is Fast

Lately I’ve been using a lot of yarn over npm, just feels snappier.

Conclusion

I’m rather happy how the site turned out due to the well-thought-out design of Elmstatic that leaves plenty of room for customization and having Elm as an ally when creating layouts and styles is always a breeze.

It’s been a great experience, thanks Alex Korban for Elmstatic!