Markdown Usage

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: 19_th

Subscript: H₂O

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. ¹

Footnote 2 link. ²

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:

• 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!

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.

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 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: The 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:

• Basic link
• Link with title
• Autoconverted link https://github.com/remarkjs
• Cross page absolute link for single page app navigation.
• Link to part of a page
• Linking with image:

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>

Toggle Me

...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:

---

Oftentimes, you need to display a code example on the page. This example could be as simple as a one-liner or as complex as a diff view. Below are the ways you can use fenced code blocks with NextBook.

Wrap your code using triple ``` characters for the simplest code formatting.

1```
2Everything within fenced code will
3be displayed in monospace font.
4```

results in:

1Everything within fenced code will
2be displayed in monospace font.

You can add syntax highlighting by specifying code's language after triple ```. NextBook uses PrismJS for themes and language definitions as it is currently the most complete one.

When application's theme changes, so does the fenced code theme. Try it now by pressing T.

1```jsx
2import React, { useState } from 'react'
3
4function Square(props) {
5  const [value, setValue] = useState(null)
6
7  return (
8    <button className="square" onClick={() => alert('click')}>
9      {props.value}
10    </button>
11  )
12}
13```

results in:

1import React, { useState } from 'react'
2
3function Square(props) {
4  const [value, setValue] = useState(null)
5
6  return (
7    <button className="square" onClick={() => alert('click')}>
8      {props.value}
9    </button>
10  )
11}

You can force dark syntax highlighting even on light theme. Provide dark parameter to do that. Swith to light theme by pressing T. to see code block below still using dark theme.

1```jsx dark
2import React, { useState } from 'react'
3
4function Square(props) {
5  const [value, setValue] = useState(null)
6
7  return (
8    <button className="square" onClick={() => alert('click')}>
9      {props.value}
10    </button>
11  )
12}
13```

results in:

1import React, { useState } from 'react'
2
3function Square(props) {
4  const [value, setValue] = useState(null)
5
6  return (
7    <button className="square" onClick={() => alert('click')}>
8      {props.value}
9    </button>
10  )
11}

Any code block will have automatic Copy icon clicking which copies contents of code block to clipboard unless you pass nocopy meta value to code fence.

You can display various information like title and link to source in code header.

Often you need to tell which file you are talking about. You can specify this by adding title info:

1```jsx title=somefolder/app.jsx
2import React, { useState } from 'react'
3
4function Square(props) {
5  const [value, setValue] = useState(null)
6
7  return (
8    <button className="square" onClick={() => alert('click')}>
9      {props.value}
10    </button>
11  )
12}
13```

results in:

somefolder/app.jsx
1import React, { useState } from 'react'
2
3function Square(props) {
4  const [value, setValue] = useState(null)
5
6  return (
7    <button className="square" onClick={() => alert('click')}>
8      {props.value}
9    </button>
10  )
11}

In case you need to link to original source you can pass link metadata. Now, title will be a link to the specified URL.

1```python numbered title=colors/primary_colors.py link=https://github.com/geekcomputers/Python/blob/master/Colors/primary_colors.py
2def diff(a, b):
3    """
4    TODO: fix this function!!
5    """
6    return a - b
7```

results in:

colors/primary_colors.py
1def diff(a, b):
2    """
3    TODO: fix this function!!
4    """
5    return a - b

Lines of code can have automatic numbering. Provide numbered metadata to achive that:

1```html numbered
2<!DOCTYPE html>
3<html lang='en'>
4<head>
5    <meta charset='UTF-8'>
6    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
7    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
8    <title>Document</title>
9</head>
10<body>
11    <h1>Hello World!</h1>
12</body>
13</html>
14```

results in:

1<!DOCTYPE html>
2<html lang='en'>
3<head>
4    <meta charset='UTF-8'>
5    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
6    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
7    <title>Document</title>
8</head>
9<body>
10    <h1>Hello World!</h1>
11</body>
12</html>

Code can start from any provided number. Use numbered together with startline metadata to achive that. Default startline is 1 unless provided.

1```html numbered startline=3
2<head>
3    <meta charset='UTF-8'>
4    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
5    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
6    <title>Document</title>
7</head>
8```

results in:

3<head>
4    <meta charset='UTF-8'>
5    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
6    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
7    <title>Document</title>
8</head>

In some cases there's a need to highlight/mark some lines and then describe each line seperately. Any number of lines can be marked by providing marked parameter:

1```html marked=2,5,6,10
2<!DOCTYPE html>
3<html lang='en'>
4<head>
5    <meta charset='UTF-8'>
6    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
7    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
8    <title>Document</title>
9</head>
10<body>
11    <h1>Hello World!</h1>
12</body>
13</html>
14```

results in:

1<!DOCTYPE html>
2<html lang='en'>
3<head>
4    <meta charset='UTF-8'>
5    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
6    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
7    <title>Document</title>
8</head>
9<body>
10    <h1>Hello World!</h1>
11</body>
12</html>

Sometimes you want to show which lines were added or removed from code. This can be achieved by passing related line numbers as added and removed parameters. Added lines will be highlighted with light green, removed lines with light red color. Note that displaying numbers, although works, in this case would cause a confusion as line numbers do not repeat.

1```html removed=2,8 added=3,9,10
2<!DOCTYPE html>
3<html lang='en'>
4<html lang='ja'>
5<head>
6...
7</head>
8<body>
9    <h1>Hello World!</h1>
10    <h1>こんにちは世界!</h1>
11    <p>今日は天気がいいですね。</p>
12</body>
13</html>
14```

results in:

1<!DOCTYPE html>
2<html lang='en'>
3<html lang='ja'>
4<head>
5...
6</head>
7<body>
8    <h1>Hello World!</h1>
9    <h1>こんにちは世界!</h1>
10    <p>今日は天気がいいですね。</p>
11</body>
12</html>

You can also pass every other parameter mentioned above together. Here we are adding some of them:

1```html numbered marked=2,5,6,10 title=public/index.html link=https://gist.github.com/amiroff/04d57ef025845b191d9cd30c7ca13f20 
2<!DOCTYPE html>
3<html lang='en'>
4<head>
5    <meta charset='UTF-8'>
6    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
7    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
8    <title>Document</title>
9</head>
10<body>
11    <h1>Hello World!</h1>
12</body>
13</html>
14```

results in

public/index.html
1<!DOCTYPE html>
2<html lang='en'>
3<head>
4    <meta charset='UTF-8'>
5    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
6    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
7    <title>Document</title>
8</head>
9<body>
10    <h1>Hello World!</h1>
11</body>
12</html>

To escape (prevent from displaying as highlighted code) block and simply display how fenced code is being used in source, wrap it with ~~~:

1~~~
2```html
3<!DOCTYPE html>
4<html lang='en'>
5<head>
6    <meta charset='UTF-8'>
7    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
8    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
9    <title>Document</title>
10</head>
11<body>
12    
13</body>
14</html>
15```
16~~~

will result in:

1```html
2<!DOCTYPE html>
3<html lang='en'>
4<head>
5    <meta charset='UTF-8'>
6    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
7    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
8    <title>Document</title>
9</head>
10<body>
11    
12</body>
13</html>
14```

---

MDX to markdown is the same as JSX to JS. To quote the original site,

MDX is an authorable format that lets you seamlessly write JSX in your Markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast 🚀.

... and this one:

Writing is fun again when you combine components, that can even be dynamic or load data, with the simplicity of Markdown for long-form content.

Basically, renaming your .md file to .mdx gives you ability to import and use React components as if it was a normal React or Next.js app.

Here is a small demo video for curious:

Say we have a basic React counter component like this:

components/example-counter.jsx
1import React, { useState } from 'react'
2export default function Counter() {
3  const [count, setCount] = useState(0)
4
5  return (
6    <div className='border border-gray-500 p-2 m-10 rounded-md bg-gray-700 text-gray-100'>
7      <p>You clicked {count} times!</p>
8      <button
9        onClick={() => setCount(count + 1)}
10        className='rounded border border-gray-500 bg-gray-900 p-1 mt-2'
11      >
12        Click me
13      </button>
14    </div>
15  )
16}

If you need to use components in your markdown content files, use .mdx extension, and provide any custom components through the components/component-mapper.jsx file. Then include it in your .mdx file and display it just like in React application:

1### Example Counter Component
2<Counter />

becomes:

Voila! This way you can create dynamic components for your documentation like never before. Live code editors, quizes, exams, cheatsheets, comments, you name it. Possibilities are endless. Notice that you can use tailwindcss classnames in components for styling.

For more information what can be achieved with MDX, see the official site.

Footnotes

¶

1. Footnote can have markup ↩

2. Footnote text. ↩