DEV Community

Adam Hill
Adam Hill

Posted on

1

Why I built another static site generator: A love story

Does the world need another static site generator? Honestly... no. But, does it deserve another one? YES!

It all started from this tweet:

If I wanted to make a static website with just a few dynamic elements that didn't look half bad, what stack should I use?

I have used a few static site generators over the years including Hugo, Jekyll, and Pelican to host my personal blog. And I have experimented with a few others including Lektor and Gatsby.

All static site generators do basically the same thing, but they each have their own idiosyncrasies. Since I have a lot of experience with Django (and a predilection to want to improve the Django ecosystem) when I saw the tweet above I thought, "why wouldn't you use Django for this?"

The reasons to use Django:

  • it's already solved a lot of tablestake features:
    • creating RSS feeds
    • sitemap.xml generation
    • auto-reloading dev server
  • a nice CLI management command system
  • Django template language with lots of built-in template tags
  • there is a huge ecosystem of other functionality

The reasons not to use Django:

  • it's "big" and "heavyweight"
  • it's over-complicated

No programming language or framework is perfect, but the one I have the most experience with is Django. I love most of the Django, but I wanted to see if I could build an opinionated framework on top that hid all of the complexities of a normal Django site (e.g. serving static assets, complicated settings files, setting up URL routes, etc).

I wanted to make Django even more lovable by creating a simplified content framework that served markdown files in an intuitive way. So, coltrane was born.

First, I used django-microframework as inspiration for a simple app.py that could be used instead of the potentially overwhelming files Django normally uses for a site. Then, I added in automatic reading of .env files to override Django settings that shouldn't be committed. I used markdown2 to automatically render markdown files into HTML. And built a way to load data from JSON into templates to be used as variables (since a database is not available when generating a static site).

Then finally, I built a management command that output the whole site as static HTML. The result is "yet another" static site generator, but a key differentiator is that it tries to be as simple as possible with sane defaults. There are only three commands:

  • poetry run coltrane create to create a new static site
  • poetry run coltrane play to start up a development server
  • poetry run coltrane record to output a static site

After the site is created, just start adding markdown files into the content directory and they will be rendered as HTML using filename as the URL slug.

coltrane won't ever solve every use-case, but right now it solves two specifically for me:

  1. It generates the static site of https://alldjango.com (building automatically on every git push by render.com).
  2. It is used to serve https://devmarks.io/articles, as a Django app in an existing Django site

So, maybe the world doesn't need another static site generator, but hopefully coltrane is a fresh take on static site generators.

I would love for you to try it out for your next project and star the coltrane repo if it looks useful!

Image of Timescale

Timescale – the developer's data platform for modern apps, built on PostgreSQL

Timescale Cloud is PostgreSQL optimized for speed, scale, and performance. Over 3 million IoT, AI, crypto, and dev tool apps are powered by Timescale. Try it free today! No credit card required.

Try free

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

👋 Kindness is contagious

Engage with a sea of insights in this enlightening article, highly esteemed within the encouraging DEV Community. Programmers of every skill level are invited to participate and enrich our shared knowledge.

A simple "thank you" can uplift someone's spirits. Express your appreciation in the comments section!

On DEV, sharing knowledge smooths our journey and strengthens our community bonds. Found this useful? A brief thank you to the author can mean a lot.

Okay