Writing in Markdown

Atlas supports writing in Markdown, a plain-text formatting syntax that can exist alongside raw HTML. The Markdown Syntax Guide has all the details you'll need. This document will highlight parts of the Markdown syntax as well as document a few additions to how we use Markdown in Atlas. Files ending in .md, .mdown or .markdown will be converted to HTMLBook when building. Markdown files in Atlas can be edited using the Code Editor.

Warning

Markdown is best for simple content. It does not support many standard technical book elements, including parts, admonitions, sidebars, and cross references. If you want to write in a wiki-like format but need a more robust feature set, we recommend using AsciiDoc.

Syntax

Headings

To insert headings with Markdown, use a number of hash symbols (# ) equal to the heading level. The top heading has one hash (# ) and the smallest heading has six hashes (###### ).

Example:

# H1
## H2
### H3
#### H4
##### H5
###### H6

Text Formatting

Italics

For italic text, surround the text you wish to be italic in single underscores (_ ) or single asterisks (* ).

Example:

_italic text_ not italic
*italic text* not italic

Bold

For bold text, surround the text with two underscores (__ ) or two asterisks (** )

Example:

__bold text__ not bold
**bold text** not bold

Strikethrough

For strikethrough text, surround the text with two tildes (~~ ).

Example:

~~strike through~~ no strike through

Code

Inline Code

For inline code markup, use backticks (` ) around the code text. This will output a code  element.

Example:

Here is a variable declaration `var x = 3;` in Javascript.

Code Blocks

There are two options for code blocks. The first is the default Markdown syntax using four spaces to start a code block. Be sure to leave an empty line before and after a code block.

Example: 

This is regular text.

    // This is code
    var x = 3;

Back to regular text

 The other way to make code blocks is to use three backticks (``` ) on lines above and below the code. This is referred to as fenced code blocks and is part of Github Flavored Markdown.

Example:

This is regular text

```
// This is code
var x = 3;
```

Back to regular text

Syntax Highlighting

Using fenced code blocks you can also specify a language to highlight the code

This is regular text

```javascript
// This is code
var x = 3;
```

Back to regular text

Lists

Itemized Lists

For itemized lists without numbering, type a separate line for each item with one of the following and a space beginning the line: * , - , +.

Example:

- List Item
- Next Item
- Another Item

Numbered Lists

For numbered lists, use numbers followed by a period. If the numbers you use are not sequential they will be converted to be sequential.

Example:

1. First item
2. Second item
3. Third item

Nested Lists

To nest a list within another, indent the child list using 4 spaces.

Example:

- Parent List
- Another item
    - Child List
    - Second Item
- One more item
    1. You can mix list types
    2. With numbered and itemized

Multiparagraph List Items

Since Markdown uses newlines to delineate the end of elements, to have a multi-paragraph list item, indent the new paragraph to the same level as the start of text in the list item. For more clarity, here is an example.

Example:

*   A list item.

    With multiple paragraphs.

*   Bar

Blockquotes

To represent some text as a blockquote, begin each line of the quote with an angle bracket (> ).

Example:

Now I will quote something.

> To represent some text as a blockquote, begin each line of the quote with an angle bracket (>).

Now I will quote something.

To represent some text as a blockquote, begin each line of the quote with an angle bracket (>).

Tables

Using the pipe (|) character you can insert tables with Markdown. Lining up the pipes is optional but will probably be easier to read in Markdown. Tables must have header rows separated by a row of dashes.

Example:

| Titles | Required |
|--------|----------|
| Simple | 1        |
| Table  | 2 |
|Example | 348978   |

Alignment in Tables

By including colons on either or both sides of a table divider, you can align that column to left, right or center.

Example:

|  Left    |    Right |  Center  |
| -------- | --------:|:--------:|
| 1        | 1        | 1        |
| 14       | 14       | 14       |
| 9823764  | 9823764  | 9823764  |
Left Right Center
1 1 1
14 14 14
9823764 9823764 9823764

Equations

To specify math markup, equations must be wrapped in a <span class="math-tex" data-type="tex"> tag and set off with \\( and \\) delimiters. For example:

<span class="math-tex" data-type="tex">\\(\pi=3.14\\)</span>

Will render like this:

\(\pi=3.14\)

Note

Backslash-parentheses delimiters are required for math with Atlas. Atlas uses MathJax, which ignores dollar-sign ($) delimiters by default.

Writing Markdown for HTMLBook

Markdown was designed for writing for the web, HTMLBook is designed for writing books. As such, HTMLBook is designed for structure, chapters, sections, and tables of contents. The conversion process from Markdown to HTMLBook attempts to add structure.

Converting Headers into Chapters and Sections

Atlas uses headings from Markdown files to create book sections. This section will explain how this happens and the requirements for using headings.

Chapters

Each file in Atlas is treated as a new chapter, and each chapter must have a title. The first line of a Markdown file must start with a single pound sign (# ) and a title:

# Title of Chapter

All subsequent content until the next # heading will be in the same chapter.

Heading to Section Conversion Chart

Markdown Heading HTMLBook Section Type
# Chapter
## Sect1 e.g., 1
### Sect2 e.g., 1.1
#### Sect3 e.g., 1.1.1
##### Sect4 e.g., 1.1.1.1
###### Sect5 e.g., 1.1.1.1.1