cri.dev
about posts rss

devblog: yet another static site generator, seriously

Published on
Last updated
Tagged with devblog1 blogging4 javascript58

devblog is yet another lightweight static site generator.

Although there are widely used SSG like 11ty (which this blog was previously based on), Jekyll (also previously used), GatsbyJS and many others, I wanted to get my hands dirty and understand how to make the process of building a static blog even simpler, if possible.

Even simpler in the sense of “it does just what I need and nothing more”.

Install via npm i -g devblog or create a blog with a one-liner npx devblog init my-new-blog, cd my-new-blog and serve with npx http-server _site 8080. It’s that easy.

Rebuild the blog by running npx devblog (or npm i -g devblog and then just run devblog in the main directory)

Continue reading my story of building devblog.

Why would you waste your time like this?

Good question.

  • to practice TDD and Refactoring skills
  • to scratch a personal programming itch
  • to create something I can use for my personal needs, and ideally someone else finds it useful too
  • to dig deep into a topic to get the most out of it
  • to personalize the experience while building my blog
  • to acquire new knowledge
  • to have fun 👨‍💻

devblog-npm-package.png

Learned

Learned or improved knowledge about:

  • TDD and Refactoring
  • CI & CD with github actions build + test + npm publishing
  • running scripts with npx
  • making a simple cli
  • YML front-matter
  • file globbing in Node.js with glob
  • HTML and CSS minification with html-minifier and clean-css
  • nunjucks template engine
  • markdown parsing with remarkable
  • testing with ava
  • recursively cleaning directories with rimraf
  • read and merge a custom user config and use in application (see custom template, functions and filters to use in nunjucks)
  • and I think lots of small things along the way

That’s just to show how much you can learn if you try to build it yourself.

Tailored to my needs

What I need for my personal blog are the following points.

  • an api
  • speed
  • cache
  • flexibility
  • tests
  • developer experience

Easy programmatic API to include data

You can easily render static data, for example your GitHub contributions:

...
  collections: {
    contributions: require('./_data/contributions.json')
  },
...

The concept here is: Take a data source, normally a JSON file, and use it through via nunjucks templates and interpolate it in JavaScript files for rendering it on the browser.

This was also possible in 11ty btw, nothing new here.

Speed 🏎

I can build my blog with 250+ files, of which ~120 blog posts and markdown files in under 10 seconds.

With Jekyll or 11ty this was a lil bit slower, but still very usable.

The thing that made me ditch Jekyll and 11ty were its dependencies.

Jekyll needed Ruby, gems, bundles and god knows what else. There is also the possibility to build your site via Docker, but come on.

11ty was the closest to my favourite tools for building my site, although it slowed down over time as I added new blog posts and files. The installation on the CI took also a bit longer than expected, with 32 dependencies (devblog uses 8 dependencies). But that would be also feasible if you install globally and cache correctly… (of course 11ty offer much much more… maybe too much for me)

That said, I still think 11ty it’s still one of the most valid alternatives for building a static site 👍.

It’s pretty fast too!

Caching

I’m currently working on a simple caching idea to avoid doing work that is not needed while building the site, especially during development.

E.g. If the hash of a file hasn’t changed since the last build, there’s no need to build it again.

This should speed up the whole process.

To do so, when building your static site with devblog, a site.json file is created (pretty huge JSON) with all the build information collected, including MD5 hashes.

Programmatic access to site resources

The site.json file can also be used to programmatically access your blog posts with third-party tools, just by reading the JSON file.

An example?

I built a small Buffer automation tool for my blog.
It programmatically logs in to buffer, takes the last 10 featured blog posts (using site.json) and adds them to the publishing queue, with Puppeteer. Fully automated.

Flexibility

devblog uses nunjucks by Mozilla under the hood, as I found it the most lightweight and powerful templating language for JavaScript.

You can define layouts, templates, interpolate variables, loop through them and so much more

Tests? Of course!

How would you build software anyways, other than with tests, refactoring and clean code in mind?

devblog is built from the ground up with tests and tries to cover most use cases.

Having tests doesn’t mean it’s defectless and perfect, it just means you covered with tests the known cases.

So, surely it might break, but adding new features, maintaining the software and fixing defects will be much, much easier. Trust me on this.

devblog-tests.png

### Developer experience

The DX is an important part when using software, at least for me.

I don’t want to spend my time downloading huge tools, to later wait again and struggle with the tool.

A tool should be easy, intuitive, lightweight and flexible to use.

If it doesn’t comply with my needs, I’m gonna switch (or build my own).

devblog tries to be as lightweight as possible, it provides a simple API to interact with it and I think it’s pretty flexible and can be tailored to your needs.

Open Source and GPL licensed

You can find the source here, if you’re interested in how it works internally: github.com/christian-fei/devblog

Let me know if you can make use of it, found it useful or a total waste of yours and my time :)

I had fun nevertheless 👨‍💻

Here, have a slice of pizza 🍕