Markdown Usage

While this is not a complete markdown reference, here are markdown features that you can use right away in your books.

Tags:#markdown#reference#NextBook#md

Front Matter

YAML front matter can be used to add title, description, part info, tags and update date to your pages. This page includes a front matter like this:

1---
2part: Documentation
3title: Markdown Usage
4description: While this is not a complete markdown reference, here are markdown features that you can use right away in your books.
5tags: [markdown, reference, NextBook, md]
6updated: '2021-03-14'
7---

HTML Tags

Markdown allows using html tags except scripts. This way you can use modern html5 tags, embed audio and video and everything else not covered by standard markdown.

Text Manipulation

1**This is bold text**
2
3_This is italic text_
4
5**_This is bold italic text_**
6
7~This is strikethrough text~
8
9Superscript: 19<sub>th</sub>
10
11Subscript: H<sub>2</sub>O
12
13This is <mark>highlighted</mark> text.

results in:

This is bold text

This is italic text

This is bold italic text

This is strikethrough text

Superscript: 19th

Subscript: H2O

This is highlighted

Horizontal Lines

Both of these work:

1---
2***

results in:



Blockquotes

1> Here is a blockquote.
2
3> Blockquotes can also be nested...
4>
5> > ...by using additional greater-than signs right next to each other...
6> >
7> > > ...or with spaces between arrows.

results in:

Here is a blockquote.

Blockquotes can also be nested...

...by using additional greater-than signs right next to each other...

...or with spaces between arrows.

Footnotes

1Footnote 1 link. [^first]
2
3Footnote 2 link. [^second]
4
5[^first]: Footnote **can have markup**.
6
7[^second]: Simple footnote text.

results in:

Footnote 1 link. 1

Footnote 2 link. 2

Code

A special care was given to displaying code on screen.

Inline Code

1`$ rm -rf /`

results in: $ rm -rf /

Fenced Code Blocks

Most of the time you'll use codefences. Here is a simple example, but you can do a lot more with them. For advanced fenced code block usages, see Fenced Code chapter.

1```bash
2#!/bin/bash
3echo "Hello World"
4```

results in:

1#!/bin/bash
2echo "Hello World"

Lists

Unordered List

1- Create a list by starting a line with +, -, or *
2- Sub-lists are made by indenting 2 spaces:
3  - Marker character change forces new list start:
4    * Facilisis in pretium nisl aliquet
5    - Nulla volutpat aliquam velit
6+ Very easy!

results in:

  • Create a list by starting a line with +, -, or *
  • Sub-lists are made by indenting 2 spaces:
    • Marker character change forces new list start:
      • Facilisis in pretium nisl aliquet
      • Nulla volutpat aliquam velit
  • Very easy!

Ordered List

11. Lorem ipsum dolor sit amet
22. Consectetur adipiscing elit
33. Integer molestie lorem at massa
44. You can use sequential numbers...
51. ...or keep all the numbers as `1.`

results in:

  1. Lorem ipsum dolor sit amet
  2. Consectetur adipiscing elit
  3. Integer molestie lorem at massa
  4. You can use sequential numbers...
  5. ...or keep all the numbers as 1.

Checkboxes

These are often used to indicate task items.

1- [x] Clone repo
2- [x] Create some pages
3- [ ] Commit & Push
4- [ ] Deploy!

results in:

  • Clone repo
  • Create some pages
  • Commit & Push
  • Deploy!

Tables

Tables are a bit tricky, because you have to use all those pipes, but this is how markdown was designed. Using a special markdown editor like Typora will make your life easier with these.

Standard Columns

1| Option | Description                                                 |
2| ------ | ------------------------------------------------------------|
3| data   | path to data files to supply the data passed into templates.|
4| engine | engine to be used for processing templates.                 |
5| ext    | extension to be used for dest files.                        |

results in:

OptionDescription
datapath to data files to supply the data passed into templates.
engineengine to be used for processing templates.
extextension to be used for dest files.

Right Aligned Columns

1| Option | Description                                                   |
2| -----: | ------------------------------------------------------------: |
3| data   | path to data files to supply the data passed into templates.  |
4| engine | engine to be used for processing templates.                   |
5| ext    | extension to be used for dest files.                          |

results in:

OptionDescription
datapath to data files to supply the data passed into templates.
engineengine to be used for processing templates.
extextension to be used for dest files.

Mixed Columns

1| Left-aligned | Center-aligned | Right-aligned |
2| :----------- | :------------: | ------------: |
3| git status   | git status     | git status    |
4| git diff     | git diff       | git diff      |

results in:

Left-alignedCenter-alignedRight-aligned
git statusgit statusgit status
git diffgit diffgit diff

Images

You will use images a lot! Drop your images or svg vectors in public folder and link to them. NextBook will autoscale them for small displays. You can add captions and alt information to your images.

1![The Octocat](/images/octocat.png) 
2![The Surface](/images/surface.jpg 'The Surface Device')

results in:

he OctocatFigure: he Octocat
The SurfaceFigure: The Surface

If you use Excalidraw svg drawings and want them to change colors accordingly in dark mode, add |ex to image alt text. See below example in light/dark modes:

1![Git Branching|ex](/images/git-branching.svg)

results in:

Git Branching|exFigure: Git Branching

Links can be auto-detected, but it would be better to be implicit and have support other markdown tools. Also, all external links in your documentation will be autodetected and appropriate html code will be generated.

1- [Basic link](https://github.com)
2- [Link with title](https://github.com 'Github FTW')
3- Autoconverted link https://github.com/remarkjs
4- Cross page [absolute link](/nextbook/getting-started) for single page app navigation.
5- Link to [part of a page](#links)
6- Linking with image: 
7- [![Deploy with Vercel raw][1]][2]
8
9[1]:  https://vercel.com/button
10[2]:  https://vercel.com/new/git/external?repository-url=https%3A%2F%2Fgithub.com%2Famiroff%2FNextBook "Deploy With Vercel now!"

results in:

Notifications

These are custom features often needed to display hints. I find them very useful.

Hints

1!> A Hint Title
2Make sure to check out [Markdown Guide](https://www.markdownguide.org/) to check the basic markdown syntax you can use with NextBook.

results in:

A Hint Title
Make sure to check out Markdown Guide to check the basic markdown syntax you can use with NextBook.

Warnings

1?> And Warning Title
2Try to keep usage of html elements to rare cases where standard markdown does not cover your basic markup needs.

results in:

And Warning Title
Try to keep usage of html elements to rare cases where standard markdown does not cover your basic markup needs.

Errors

1x> An Error Title
2Ooooops, an unknown error occured.

results in:

An Error Title
Ooooops, an unknown error occured.

Emojis

Nothing fancy, just use native os supported 🥳 emoji characters or their text representations like :partying_face: for 🥳.
Press control + command + space on macOS and windows + . on Windows.

Containers

Accordion

1<Accordion title="Toggle Me">
2...and see my content
3</Accordion>
Toggle Me

...and see my content

Warning
Accordion component is not print compatible. Use responsibly.

Tabs

While markdown spec does not offer any tabbed interface, NextBook has you covered here. Use tabs and tab containers as follows:

1<Tabs>
2  <Tab title="Windows Directions">
3      Install via [chocolatey](https://chocolatey.org):
4  
5      `choco install python`
6  </Tab>
7  <Tab title="macOS Directions">
8      Install via [brew](https://brew.sh):
9
10     `brew install python3`
11  </Tab>
12  <Tab title="Linux Directions">
13      Install via apt:
14
15      `sudo apt install python3`
16  </Tab>
17</Tabs>

results in:

Install via chocolatey:

choco install python

Footnotes

  1. Footnote can have markup

  2. Footnote text.


Last Update: March 14, 2021