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
Links and Images
Automatic Linking
URLs starting with http://
will automatically be converted to hyperlinks in appropriate formats.
Example:
This is a link to http://oreilly.com.
Will be converted to
This is a link to <a href="http://oreilly.com">http://oreilly.com</a> [Add a title to a link](http://oreilly.com "O'Reilly")
Links
For links that don't display the URL, first type the text of the link inside square brackets ([
and ]
), and then type the URL itself surrounded by parentheses.
Example:
[This is a link to oreilly.com](http://oreilly.com)
Will be converted to
<a href="http://oreilly.com">This is a link to oreilly.com</a>
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 |