Atlas supports writing in Markdown in addition to HTMLBook. Files ending in “.md”, “.mdown” or “.markdown” will be converted to HTMLBook when building. The Markdown Syntax Guide has all the details you’ll need. This guide will highlight parts of the Markdown syntax as well as document a few additions to how we use Markdown in Atlas.
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
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
For bold text, surround the text with two underscores (__ ) or two asterisks (** )
Example:
__bold text__ not bold **bold text** not bold
For strikethrough text, surround the text with two tildes (~~ ).
Example:
~~strike through~~ no strike through
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.
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
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
URLs starting with http:// will automatically be converted to hyperlinks in appropriate formats. Meaning
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")
For links that don’t display the URL, first type the text of the link inside of square brackets ([ and ] ) and then 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>
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
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
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
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
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 (>).
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 |
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 |
Markdown was designed for writing for the web, HTMLBook is designed for writing books. As such, HTMLBook is designed for structure, chapters, sections, tables of contents. The conversion process from Markdown to HTMLBook attempts to add structure.
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.
| 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 |