The noblest static site generator 🥬

I love Darkness 🥬

Also posted here

darkness

Go Report Card GoDoc PRs Welcome

This is no life

It doesn't feel right anymore. I feel that every time I write something for my website, I have to dance to the tune of pandoc and asciidoctor. Maybe the Ruby and Haskell Gods will take pity on me and my stuff will actually 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 most noble 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 orgmode files and creates an html file for them. Orgmode is a markup language used by emacs, though it's 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 an breaking lines
  • Good placement of images and its captions
  • Embed support for: youtube, spotify, video, audio, etc.
  • Raw HTML placement and export within the page
  • Source code blocks with language selection
  • Full math render support with KaTeX (only enabled on pages with math)
  • Smart Holoscene time annotations and layovers (just hover over H.E. times)
  • Rich meta tags (OG/twitter-friendly) with previews enabled on every page
  • Creating new darkness websites from a template (use darkness new NAME)
  • 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. 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

Getting started

Want to try out darkness but don't know orgmode? 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/[email protected]

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's website that shows the formatting in action with many other cool things! It's the template website that we just made above. I do hope you find it fun here

Formatting

Here is some orgmode and darkness formatting guide! The actual formatting and final layout is here!

Sections

Every darkness input should start with the page's title. Page's title will look in the form of * Page's title and every section on the website will start with two or more astericks to show the heading level. So, ** Section and *** Subsection will be put as a child of the former.

Formatting

You can separate text into paragraphs by adding a new line between them. Think of an empty line as a delimeter. You should always add it between different types of blocks you add to your page.

Simple formatting is supported as well, you can do some bold text, maybe even italics, and verbatim. For *bold*, surround your text with astericks, for /italics/, surround with forward slashes, and verbatim with equal signs, =verbatim=

Links and embeds

Links are in the form of [­[link][text]]. If your link is in a text, then it will show up as such. If the link is on a separate line, darkness will decide if it can be inserted as an embed (image, youtube, spotify song/playlist, video, audio).

Images

See for example, below is a link on its line with an image path

CUT, August 2009 issue. Art by Tadashi Hiramatsu

Songs

Depending on the link type, darkness will intelligently stub in a preview if it's a standalone link (not inlined within text). One more example

Last Surprise

Lists

Lists are created by starting a line with a hyphen followed by an item description, you would write something like

- This is my first item
- This second item is going to be so long that I would
have to break it down into two line
- Third item follows swiftly

It will render as follows

  • This is my first item
  • This second item is going to be so long that I would have to break it down into two line
  • Third item follows swiftly

Source code blocks

Source code blocks follow orgmode's conventions. You would wrap your source code with #+begin_src LANG and #+end_src, where LANG is the language of the source code block. You can leave LANG empty as well.

#+begin_src c
main( ) {
        printf("hello, world");
}
#+end_src

Will render as (hover over the block to see the language)

main( ) {
        printf("hello, world");
}

HTML injection

Whatever darkness provides can still be limiting if you want to insert some of your own material or embeds that are not supported. Do you give up? Hopefully not. Anything surrounded by #+begin_export html and #+end_export will be inserted literally into the page.

<script src="https://gist.github.com/thecsw/c80f83c0d52c0a476e86fc9a6a980517.js"></script>

This is the embed source for the above

#+begin_export html
<script src="https://gist.github.com/thecsw/c80f83c0d52c0a476e86fc9a6a980517.js"></script>
#+end_export

Attention blocks

You may need to grab reader's attention even more or make them aware of some sharp edges in whatever you're writing about. Start a paragraph with NOTE:, IMPORTANT:, CAUTION:, TIP:, or WARNING:, and you will get an attention-grabber

TIP: This is kinda useful for technical posts when you mention exceptions or so

Footnotes

Another cool thing darkness can do for you is keeping track of your footnotes. We follow orgmode's conventions as well. Anywhere in the text, if you have a string in the form of [fn­:: blablabla], that blablabla will go and become your footnote. 1

Niche features

See this cool trick of cleaning up the project with megumin!

My name is Megumin, the number one mage of Axel!

Why "Darkness"?

Her name is based one one of the characters I love from KonoSuba

Dustiness Ford Lalatina

A knight must never run away, no matter how mighty the enemy. -- Darkness

Footnotes

  1. Formatting also works in footnotes

Similar Resources

XSD (XML Schema Definition) parser and Go/C/Java/Rust/TypeScript code generator

xgen Introduction xgen is a library written in pure Go providing a set of functions that allow you to parse XSD (XML schema definition) files. This li

Dec 3, 2022

GObject-introspection based bindings generator

WARNING! This project is no longer maintained. Probably doesn't even compile. GObject-introspection based bindings generator for Go. Work in progress

Jan 5, 2022

Typo/error resilient, human-readable token generator

toktok A human-friendly token generator Creates tokens which avoid characters that can be easily misinterpreted, like '1' and 'I' or '8' and 'B', as w

Sep 16, 2022

Fast and secure initramfs generator

Fast and secure initramfs generator

Booster - fast and secure initramfs generator Initramfs is a specially crafted small root filesystem that mounted at the early stages of Linux OS boot

Dec 3, 2022

Jennifer is a code generator for Go

Jennifer Jennifer is a code generator for Go. package main import ( "fmt" . "github.com/dave/jennifer/jen" ) func main() { f := NewFile("m

Dec 2, 2022

General Golang Code Generator

gg gg is a General Golang Code Generator: A Good Game to play with Golang. package main import ( "fmt" . "github.com/Xuanwo/gg" ) func main() {

Nov 2, 2022

Default godoc generator - make your first steps towards better code documentation

godoc-generate Overview godoc-generate is a simple command line tool that generates default godoc comments on all exported types, functions, consts an

Sep 14, 2022

accessor methods generator for Go programming language

accessory accessory is an accessor generator for Go programming language. What is accessory? Accessory is a tool that generates accessor methods from

Nov 15, 2022

RinkWorks fantasy name generator in golang

RinkWorks fantasy name generator in golang

Nov 10, 2022
Giraffe - An opinionated static site generator written in Go

Giraffe: An opinionated static site generator I want to start 2022 by writing a

Nov 18, 2022
A static blog generator for telling tall tales

Gleeman Gleeman is a toy static blog generator that aims to be a simple way to tell tales. The term "gleeman" is taken from Robert Jordan's epic fanta

Jan 14, 2022
Shopping Cart for a fictional e-commerce site.

A shopping cart for a fictional e-commerce site. Main objective is to create REST APIs for some specific request/endpoints.

May 19, 2022
QuickAbeHiroshi - The golang program to open a web site which is the fastest in the world
QuickAbeHiroshi - The golang program to open a web site which is the fastest in the world

The golang program to open a web site which is the fastest in the world.

Jan 2, 2022
🦉 Docuowl generates a static single-page documentation from Markdown files
🦉 Docuowl generates a static single-page documentation from Markdown files

?? Docuowl generates a static single-page documentation from Markdown files

Dec 1, 2022
Random fake data and struct generator for Go.

Faker Random fake data and struct generator for Go. More than 100 generator functions Struct generator Unique data generator Builtin types support Eas

Oct 3, 2022
Random fake data generator written in go
Random fake data generator written in go

Gofakeit Random data generator written in go Features 160+ Functions!!! Concurrent Global Rand Struct Generator Custom Functions Http Server Command L

Dec 1, 2022
A distributed unique ID generator of using Sonyflake and encoded by Base58

Indigo About A distributed unique ID generator of using Sonyflake and encoded by Base58. ID max length is 11 characters by unsigned int64 max value. A

Nov 24, 2022
:guardsman: A teeny tiny and somewhat opinionated generator for your next golang project

A Yeoman Golang Generator We are very sorry Gophers, but other names for the generator where taken, so we choose go-lang. But we have gocreate as an a

Sep 27, 2022
Unit tests generator for Go programming language
Unit tests generator for Go programming language

GoUnit GoUnit is a commandline tool that generates tests stubs based on source function or method signature. There are plugins for Vim Emacs Atom Subl

Nov 28, 2022