Welcome, Ishmael. This is your website built with darkness. Let me give you a tour of all the incredible adventures that are waiting for you beyond the horizon. What you see here right now, is a simple block of text.

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 = or ~code~

Some new ones were added, such as ~~strike-through~~ (+strike-through+) and underline (underline).

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

YouTube videos

If you just have a youtube link by itself on a line, it will embed the video player in a responsive container and everything! (embeds might not work locally, you would need to push it somewhere)

Galleries

You can begin galleries with = image should be in a list. You can pass an optional :num N to the begin_gallery to define the custom number of flex elements per row (defaults to 3). You can even change the width of each list element manually by passing :flex W parameter in the list line, where W is the percentage in increments of 5 starting from 30.

Here is an example of a custom width element to have that woah effect.

You can also improve user’s experience by generating very cheap (around 10KB size) preview images, so that the DOM space is cheaply laid out before the full image has a chance to load. misa subcommand (run -help) provides quality of life improvements that are extra to the build.

darkness misa -gallery-previews

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.

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

/* you always say hi but it never replies */
main( ) {
        printf("hello, world");
}

Special environments

You can center text or add quotes org-mode style with #+begin_center and #+end_center, so

it would look like this

or you can also wrap your quotes in #+begin_quote with #+end_quote for the following,

There is nothing more awful, insulting, and depressing than banality.

– Anton Chekhov

or you can have details with #+begin_details <NAME> and #+end_details,

this is the title

ha! you found me

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.

Simply wrap any raw HTML (like script tags) in #+begin_export html and #+end_export if you want the code injected within the article container or #+begin_export html_raw to inject it in the root DOM.

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

IMPORTANT

Life is to be lived.

Adding 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. ^I

Tables

Tables are super cool, by making an orgmode table and optionally adding a caption above it with #+caption: blablabla, we can get the following,

This is my very cool table

Name	Origin	Waifu?
Rem	Re:Rezo	YES YES YES
Aqua	Konosuba	Absolutely.
Zero Two	Darling in the FRANXX	`no other way`
Najimi	Komi Can’t Communicate	yes

Drop caps

Drop a nice #+drop_cap above any paragraph and it will make this nice old style section division.

I Formatting also works in footnotes

Ishmael’s Moby 🐋