While this is not a complete markdown reference, here are markdown features that you can use right away in your books.
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---
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.
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
Both of these work:
1--- 2***
results in:
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.
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
A special care was given to displaying code on screen.
1`$ rm -rf /`
results in: $ rm -rf /
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"
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:
+
, -
, or *
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.
These are often used to indicate task items.
1- [x] Clone repo 2- [x] Create some pages 3- [ ] Commit & Push 4- [ ] Deploy!
results in:
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.
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:
Option | Description |
---|---|
data | path to data files to supply the data passed into templates. |
engine | engine to be used for processing templates. |
ext | extension to be used for dest files. |
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:
Option | Description |
---|---|
data | path to data files to supply the data passed into templates. |
engine | engine to be used for processing templates. |
ext | extension to be used for dest files. |
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-aligned | Center-aligned | Right-aligned |
---|---|---|
git status | git status | git status |
git diff | git diff | git diff |
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:
Figure: he Octocat
Figure: 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:
Figure: 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:
These are custom features often needed to display hints. I find them very useful.
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.
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.
1x> An Error Title 2Ooooops, an unknown error occured.
results in:
An Error Title
Ooooops, an unknown error occured.
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.
1<Accordion title="Toggle Me"> 2...and see my content 3</Accordion>
...and see my content
Warning
Accordion component is not print compatible. Use responsibly.
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