144; 12022 H.E.
This was originally published on
This is no life
It doesn’t feel right anymore. Every time I write something for my website, I feel that I have to dance to the tune of
asciidoctor. Maybe the Ruby and Haskell Gods will take pity on me and my stuff will render as I want them to. Oh... they didn’t? Time to write a new
sed script to fix that.
This is no life. Instead of fixing an issue at its root, I've been writing fixes, patches, and this. It was fun in the beginning! Mastering sed and awk, the forbidden tools echoed from the past. However, as time went on and I wanted to add more content and get more freedom, this pipeline felt limiting.
A hero emerges
It is my honor and pleasure to introduce you to Darkness! The noblest, static website generator. The website you are on right now is built by her, with all the images, styling, embeds, and more! The big advantage of Darkness is that she is general enough (with a config file), so she can build any website for what their heart desires.
Darkness currently takes a subset of org-mode files and creates an HTML file for them. Org-mode is a markup language used by emacs, though it’ very similar to markdown. There is a getting started portion further! It will get you everything you need to get comfortable with the process. Also, darkness is more agnostic than just org->html. One just has to write a parser/exporter for a markup language, enable it, and now we have multiple supported types!
Plethora of features
Darkness supports a vast array of features and cool tricks, such as
Project configuration with a simple toml file
Smart headings (laid out and shifted as needed)
Paragraphs with full orgmode-style formatting
Lists with any text and breaking lines
Good placement of images and their captions
Orgmode environments, like
Embed support for: youtube, Spotify, video, audio, etc.
Raw HTML placement and export within the page
Orgmode interactive tables support
Stylistic features, like dropcaps
Source code blocks with language selection
Full math render support with KaTeX
Smart Holocene time annotations and layovers
Rich meta tags with previews enabled on every page
Creating new darkness websites from a template
Project cleanup and maintenance tools included with the binary
Open-source code, PRs, and contributions are welcome!
Not only noble but also super fast
Darkness is also lightning fast! With the old pipeline, it would take around 8-10 seconds to build my website. Darkness only takes ~100ms to do the same, with IO and memory syscall times included. This is why profiling should be your friend. She uses some cool parallelization tricks, so we spend around 1ms on each page. Pretty cool if you ask me. The fastest (though admittedly larger) static website generators took a bit more time in my experience.
sandyuraz:source* λ darkness build Looking for files... found 83 in 23 ms Building and flushing... done in 65 ms farewell
Want to try out darkness but don’t know org-mode? You are at the very start of something beautiful, my friend! If you have go 1.18+ installed, run the command below to get the latest version of her (you can also grab a suitable binary from the releases page)
go install -v github.com/thecsw/darkness@latest
Next, go to the place, where you would like to hous your next website. Call her with a
new command followed by any name that feeds your soul (
ishmael is an example here)
darkness new ishmael
Voilà! You have a new darkness project initiated. Change into that new directory with
cd ishmael and type in
darkness build. You’ll find an
index.html in the root, go open it! After that, look into
darkness.toml, which shows you the number of things you can play with to change the looks and feel.
Here is Ishmael’ website that shows the formatting in action with many other cool things! It’ the template website that we just made above. I do hope you find it fun here
See this cool trick of cleaning up the project with
Her name is based on one of the characters I love from KonoSuba
A knight must never run away, no matter how mighty the enemy. — Darkness ◼︎