Elmstatic, my Elm-to-HTML static site generator, upgraded to Elm 0.19!
2019-04-16

Last year, I released my Elm-to-Html static site generator, Elmstatic.

As it relied on elm-static-html-lib (which I wrote about), I had to wait for this library to be updated to Elm 0.19 first. However, the update didn’t happen, possibly because it relied on the now defunct Elm native modules, or because the author has moved on to other things.

I finally rolled up my sleeves and came up with a different solution, changing a lot of the inner workings in the process.

The current set of features is:

  • Pages generated from Elm code (you can use elm-ui, html or any other package that generates Html msg values)
  • CSS generated from elm-css stylesheets in Elm code (but you can use plain old stylesheets if you like)
  • Page templates for posts and lists of posts (fully customisable)
  • Optional subsections with separate streams of posts (eg /postgres and /elm on this site)
  • The content of posts and pages is written in Markdown
  • Posts can have multiple tags
  • A page with a list of posts is generated for each tag
  • RSS is generated for the posts
  • Code highlighting via Highlight.js (but you can set up whatever you want)
  • Support for draft posts

Elmstatic remains an early stage project for now: error handling is limited, and I haven’t done any performance optimisation. However, I’m using it for korban.net, so it’s not just a prototype!

What’s changed

Compared to the previous version (0.3.4), the workflow remains largely the same, but the way the content and code is organised has changed:

  • Instead of elm-ui, the scaffold generated by elmstatic now uses html and elm-css in order to provide a responsive template. You’re still free to use elm-ui or any other package that produces Html msg values, however.
  • All of the HTML is now generated via Elm code — no more template.html.
  • The set of allowed post tags is now specified in config.json instead of Elm code, as this is simpler.
  • Page content (Markdown) is now separate from layout (Elm code).
  • The directory structure of the scaffold has changed.

Note: these changes are not backwards compatible with v0.3.4.

One of the advantages of the new implementation is that because I’m able to run arbitrary JavaScript, I can convert Markdown to HTML using elm-explorations/markdown (which relies on a JavaScript library under the hood). Previously I had to use pablohirafuji/elm-markdown, a pure Elm package for parsing Markdown and rendering HTML, which had a few limitations.

How to try it

You can install Elmstatic from NPM:

$ npm install -g elmstatic

Running elmstatic init in a directory will generate a site scaffold. Change the generated files to your liking, then generate the output by simply running elmstatic without arguments.

Finally, run an HTTP server in the output directory to check out the result:

$ cd _site
$ http-server

For more details:

Comments or questions? I’m @alexkorban on Twitter.

Looking for the nuts-and-bolts guide to creating non-trivial real world apps in Elm?

My book, Practical Elm for a Busy Developer, skips the basics and gets right into explaining how to do practical stuff. Things like building out the UI, communicating with servers, parsing JSON, structuring the application as it grows, testing, and so on. No handholding — the focus is on giving you more substance.

It’s up to date with Elm 0.19.

Pop in your email to get a sample chapter.

(You will also get notifications of new posts along with other mailing list only freebies.)

Book cover