Articles are written in Markdown syntax. At first you might shy away since this is not a WYSIWYG editor, but give it a chance. Markdown is a great choice when you don't want your editors to have full control over formatting and styles. You want them to specify what kind of content they are writing, but not specifically the exact way to style and display it.
This provides a couple of benefits. First, if you decide to change the style of your documentation, you only need to edit your CSS theme, not each and every article. Second, your editors don't need to remember exactly how to format and style something. For example, with Markdown they just need to know "I want this to be a heading so I need to prefix it with ##
".
Markdown allows you to mark specific pieces of text with the normal formatting you would expect in a normal text editor. For instance, marking text as italicized, bold or strikethrough.
Italics
To make text italicized you should wrap it inside a single asterisk on either side of the text.
Example
Sometimes you need to *draw attention* to some text.
Renders As
Sometimes you need to draw attention to some text.
Bold
To make text have extra emphasis you should wrap it inside double asterisks on either side of the text.
Example
Sometimes you need to **draw attention** to some text.
Renders As
Sometimes you need to draw attention to some text.
If you need to make text both italics and bold, you would wrap it inside triple asterisks on either side of the text.
Example
Sometimes you need to ***draw attention*** to some text.
Renders As
Sometimes you need to draw attention to some text.
Strikethrough
If you need to strikethrough some text you would wrap it inside double tildes on both sides of the text.
Example
Sometimes you need to ~~remove attention~~ from some text.
Renders As
Sometimes you need to remove attention from some text.
Headings
Headings are denoted by a hash #
character at the start of the line. The number of hashes denotes the heading level. For instance, 3 hashes would be equivalent to a third level heading.
Example
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
[!TIP]
While not required, you might consider limiting yourself to heading levels 2-6. The default template will display the article title as a first-level heading. Having a single first level heading helps search engines properly index your documentation.
Lists
You have two options for building lists of items. You can use both bulleted lists as well as numbered lists.
Bulleted Lists
A bulleted list is best used for unordered items, meaning the order does not matter. To build an unordered list you prefix each line with a *
character followed by a whitespace character.
Example
* First item
* Second item
* Third item
Renders As
- First item
- Second item
- Third item
You can also have multiple levels of bulleted lists by prefixing the entire line with 4 whitespace characters before the asterisk character. Each set of four whitespace corresponds to one level of indentation.
Example
* First item
* Second level
* Third level
* Second item
* Third item
Renders As
- First item
- Second item
- Third item
Numbered Lists
Numbered lists, also called ordered lists, are best used for a sequence of items. That is, items that must be in this order for them to make sense. For example, a sequence of steps that must be performed is a good candidate for an ordered list. You create an ordered list by prefixing each line with a number, followed by a period, and then a whitespace, such as 1.
.
You can either enter your own sequential numbers or you can just always prefix each line with 1.
and it will automatically move to the next number on each line when it renders. Doing it this way can be helpful especially if the number of steps is changing quite often and you don't want to renumber the whole list each time.
Example
1. First item
2. Second item
3. Second item
Renders As
- First item
- Second item
- Third item
Just like with unordered lists, you can also indent your items by four whitespace characters. If want to change how each level is displayed you can use CSS. For instance, you might want the second level to be alphabetical starting with a
and the third level to be roman numerics starting with i
.
Example
1. First item
1. Second level
1. Third level
2. Second item
3. Third item
Renders As
- First item
- Second level
- Third level
- Second item
- Third item
Links
You will find it very easy to include a link to another page either on your site or on an external site. This comes in two parts. First you need to supply the title text that will become the clickable link. This is done by wrapping the title inside an opening bracket [
and a closing bracket ]
. Next the actual URL gets wrapped inside an opening parenthesis (
and a closing parenthesis )
.
Example
Please try our [Search](http://www.google.com/) page.
Render As
Please try our Search page.
Images
Images are handled in almost the exact same way as links, so please refer to the above section on Links for a general reference on the syntax. The difference between a regular link and an image is that the entire thing is prefixed with an exclamation !
character. When that is used, the link URL is used as the image to be displayed and the title text becomes the alternate text to display if the image can't be displayed for any reason.
Example
![Sample Image](https://dummyimage.com/800x240/fff/000&text=Sample+Image)
Renders As
Quotations
Quoted text blocks can be used for a couple different things, depending on how you want to use them. But at their most basic, they are just a different way to display text. You mark text as a quote block by starting the line with a greater than >
character. You can also use multiple >
characters to increase the level of quotation.
As the name implies though, the most common use is to indicate a piece of quoted text. In the case of documentation, you might use this for simple callouts to make the text stand out just a bit without overstating it's content.
Example
> True humility is not thinking less of yourself; it is thinking of yourself less.
>
> C.S. Lewis
Renders As
True humilty is not thinking less of yourself; it is thinking of yourself less.
C.S. Lewis
Tables
You can even design tables in your documentation. A table is defined by the first line containing the heading titles of the columns, each column has a vertical bar |
characters before and after.
The second line is the "table indicator" which tells the Markdown engine that this is a table. It is defined as one or more hyphen -
characters, also surrounded by vertical bar |
characters. Each column and optionally have a colon :
character to specify the alignment to be used for that column.
The remaining lines specify the rows and column values of the table. Each line is a row and the column values should follow the same pattern as the header line.
Example
| Heading 1 | Heading 2 | Heading 3 | Heading 4 |
| :---- | ----: | :----: | ---- |
| Left Aligned | Right Aligned | Centered | Neutral |
| 100 | 100 | 100 | 100 |
| 200 | 200 | 200 | 200 |
| 300 | 300 | 300 | 300 |
Renders As
Heading 1 |
Heading 2 |
Heading 3 |
Heading 4 |
Left Aligned |
Right Aligned |
Centered |
Neutral |
100 |
100 |
100 |
100 |
200 |
200 |
200 |
200 |
300 |
300 |
300 |
300 |
Code Examples
While you may not plan on writing actual programming code examples, the code examples is another way to highlight text. This comes in two flavors.
- Inline code samples
- Fenced code blocks
The first involves using a single back-tick `
character to open and close your inline sample.
Example
When asked to enter the contact type be sure to enter `Contact Card`.
Renders As
When asked to enter the contact type be sure to enter Contact Card
.
As you can see this highlights whatever is inside the back-ticks and also switches to using a monospace font. This syntax is common to use when you are describing something that the user should type in as-is.
The second form allows you to have multiple lines of code (or plain text). You do this by using what is called a "code fence", which is three back-ticks ```
on a line to start and then another three back-ticks ```
to close the fenced block. Optionally, after the opening three back-ticks you can also include a language alias specifier which will be used for automatic syntax highlighting.
Example
```html
<p>
This is a sample of <b>bold</b> text.
</p>
```
Renders As
<p>
This is a sample of <b>bold</b> text.
</p>
This method is common to use when showing a full example of what a user might type in. It is also useful if you just need to make sure that the text is displayed exactly as you intended, without any automatic word wrapping or anything like that being applied.
Below you will find a list of most of the supported languages for automatic syntax highlighting, there are actually more but you aren't likely to ever use them.
Alias |
Language |
applescript |
AppleScript |
aspnet |
ASP.Net |
bash |
Bash |
basic |
Basic |
c |
C |
coffee |
Coffee |
coffeescript |
Coffee Script |
cpp |
C++ |
cs |
C# |
csharp |
C# |
eiffel |
Eiffel |
fsharp |
F# |
go |
Go |
html |
HTML |
java |
Java |
javascript |
JavaScript |
js |
JavaScript |
json |
JSON |
markdown |
Markdown |
markup |
Markup |
mathml |
MathML |
md |
Markdown |
objectivec |
Objective-C |
ocaml |
OCaml |
pascal |
Pascal |
perl |
Perl |
php |
PHP |
plsql |
PL/SQL |
powershell |
PowerShell |
py |
Python |
python |
Python |
rb |
Ruby |
regex |
Regular Expression |
ruby |
Ruby |
sass |
SASS |
scss |
SCSS |
shell |
Shell |
smalltalk |
Smalltalk |
sql |
SQL |
svg |
SVG |
swift |
Swift |
ts |
TypeScript |
typescript |
TypeScript |
vb |
Visual Basic |
visual-basic |
Visual Basic |
xaml |
XAML |
xml |
XML |
yaml |
YAML |
yml |
YAML |
Alerts
Sometimes you want to draw special attention to something. It might be something informational that they might miss if they were skimming over the text and you want to draw extra attention to it. Other times you might want to point out a common error people make so they don't make the same mistake. These are called alerts and are built very similarly to a quotation.
A quotation is prefixed by one of the following words, enclosed inside a special tag: TIP
, NOTE
, WARNING
, IMPORTANT
, CAUTION
. the special tag is an opening bracket [
character, the exlemation point !
, the alert word and finally a closing bracket ]
character. For instance: [!TIP]
.
Example
> [!TIP]
> This is a tip to help the user.
> [!NOTE]
> This is a note the user should be aware of.
> [!IMPORTANT]
> This is something important that the user should pay special attention to.
> [!WARNING]
> This is a warning to the user to do or not do something.
> [!CAUTION]
> This is a caution to the user that something could be dangerous.
Renders As
[!TIP]
This is a tip to help the user.
[!NOTE]
This is a note the user should be aware of.
[!IMPORTANT]
This is something important that the user should pay special attention to.
[!WARNING]
This is a warning to the user to do or not do something.
[!CAUTION]
This is a caution to the user that something could be dangerous.