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
.markdown will be converted to HTMLBook when building. Markdown files in Atlas can be edited using the Code Editor.
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.
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 (
# H1 ## H2 ### H3 #### H4 ##### H5 ###### H6
For italic text, surround the text you wish to be italic in single underscores (
_ ) or single asterisks (
_italic text_ not italic *italic text* not italic
For bold text, surround the text with two underscores (
__ ) or two asterisks (
__bold text__ not bold **bold text** not bold
For strikethrough text, surround the text with two tildes (
~~strike through~~ no strike through
For inline code markup, use backticks (
` ) around the code text. This will output a
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.
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.
This is regular text ``` // This is code var x = 3; ``` Back to regular text
Using fenced code blocks you can also specify a language to highlight the code
For itemized lists without numbering, type a separate line for each item with one of the following and a space beginning the line:
- List Item - Next Item - Another Item
For numbered lists, use numbers followed by a period. If the numbers you use are not sequential they will be converted to be sequential.
1. First item 2. Second item 3. Third item
To nest a list within another, indent the child list using 4 spaces.
- 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.
* A list item. With multiple paragraphs. * Bar
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 (>).
Now I will quote something.
To represent some text as a blockquote, begin each line of the quote with an angle bracket (>).
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.
| 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.
| Left | Right | Center | | -------- | --------:|:--------:| | 1 | 1 | 1 | | 14 | 14 | 14 | | 9823764 | 9823764 | 9823764 |
To specify math markup, equations must be wrapped in a
<span class="math-tex" data-type="tex"> tag and set off with
\\) delimiters. For example:
<span class="math-tex" data-type="tex">\\(\pi=3.14\\)</span>
Will render like this:
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.
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|
|##||Sect1 e.g., 1|
|###||Sect2 e.g., 1.1|
|####||Sect3 e.g., 1.1.1|
|#####||Sect4 e.g., 184.108.40.206|
|######||Sect5 e.g., 220.127.116.11.1|