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=

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
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

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.

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]

1 Formatting also works in footnotes