akelei uses plain-text markdown for all its content instead of the complex and cumbersome page-building interfaces common in other site-creation and blogging software.
if you're comfortable writing in ulysses, obsidian, ia writer or one of hundreds of other popular writing tools, you already know plenty of markdown. if you're new to writing markdown, though, this is everything you need to know to write in akelei.
markdown is a popular writing standard and millions of people already use it every day. there's almost no learning curve for most people -- you just add a # for headings and ##, ### and so on for sub-headings and deeper and that's all you really need to write most of your content.
but there are more reasons than "it's easy". one is that it means your content is completely transferrable between many apps without conversion. you can write in any markdown app -- including many free ones -- and use any markdown content-organization tool. you can shift content between print and online and even automate synchronization because it's just plain text.
if you ever have problems with your content, you can send it back and forth by email without having to worry about downloading files or corrupting binary formats, whether it will look ok between macs and pcs or iphones and androids. screen size doesn't matter because plain text will always size and wrap automatically.
it's already compatible with 100% of screen readers and magnification tools because they're built to work with text. on the other side of accessibility, it's also easy to dictate using any dictation software, including the ones already built in to most modern devices.
it's also language-flexible so you can write in any script you like and nothing breaks -- you don't even have to tell it which language you're using. as long as they're valid unicode characters, markdown doesn't give a single shit what the content looks like.
if you're worried about privacy and data security, markdown also means you never have to use conversion software to go between formats, either. it's human-readable and application-ambivalent. just copy and paste and the apps will all understand your content.
headings are noted using at least one # at the beginning of a line. the number of # determines the depth of the heading. your page title should have a single #, subheadings two, sub-subheadings three and so on. you can have as many sub-headings as you like but there should only be one title. subheadings can't go beyond ######.
# title
## subheading
### sub-subheadingdon't forget to separate your headings from other content with a blank line.
headings can have ids for links, too. just add {id} at the end.
## subheading {sub1}text can be displayed as italicized, bold, crossed out, highlighted, superscript or subscript.
**bold**
*italics*
~~crossed out~~
==highlighted==
^superscript^
~subscript~lists can be ordered (numbered) or unordered (bullets).
1. abc
1. def
1. ghi
- something
- something else
- another thingyou can use the real numbers for an ordered list but, if you just number them all 1., akelei will number them for you so you don't have to worry about keeping track or adding/removing items from the list.
you can make sublists by just indenting with four spaces. (yes, numbered lists will automatically renumber if you just use 1. for every item.)
1. abc
1. azy
1. axw
1. apq
1. avu
1. def
1. dzy
1. dxw
- first item
- a sub
- another sub
- a subsub
- maybe a sub
- second item
- even more sub
- sub againakelei has its own special image display for uploaded images that is outside the markdown language because markdown doesn't support multiple image formats, automatic conversion or browser checking for compatibility.
{{image/id}}but it still supports the standard markdown image code, too. if you want to manually link to an image or use an image from somewhere else on the internet, it definitely works. you can provide alternate text or leave that blank for decorative images.
links look just like images but without the !.
[text](url)you can even link within your page if you've added id tags to any of your headings.
tables are not in the original markdown standard but most markdown apps support them now (including akelei). one small restriction is that markdown requires tables to have headings.
| first header | second header | third header |
| --- | --- | --- |
| abc | 123 | dog |
| def | 456 | cat |
| ghi | 789 | moose |
| jkl | 012 | rabbit |you can add a visual divider between elements using --- on a blank line. by default, akelei will show this as a pale gray horizontal line.
---you can separate information from the rest of your document using >.
regular paragraph.
> separated paragraph.
another regular paragraph.you can even nest them if you like.
normalcy.
> excitement.
>> utopia.
>
> sleepiness.
complacencymake sure you add a blank line at the depth you want before continuing if you want to stay inside the original separated block. nested separated blocks can be a little twitchy in practice but they are predictable once you get used to them.
if you want to write code, there are two ways. if it's inside an existing paragraph, just wrap the code in ``````.
`code`if you want whole blocks of code, wrap them in ````` `````.
```
some code
more code
even more code
```akelei will automatically highlight code for syntax in various languages. just put the language after the first ```````.
```php
function abc(){
print_r("hello world.");
}
```for footnotes and endnotes, you can use [^1].
something to reference.[^1]
[^1]: reference information.akelei will automatically create the links for you.
template codes are specific to akelei and are wrapped in {{}}. you can see them in the quick start guide. these won't work in other markdown editors but they allow you to insert items like optimized images, audio and youtube videos in your akelei content.