Introduction

Markdown and Mdx parsing is supported via unified, and other remark and rehype packages. next-mdx-remote allows us to parse .mdx and .md files in a more flexible manner without touching webpack.

GitHub flavored markdown is used. mdx-prism provides syntax highlighting capabilities for code blocks. Here's a demo of how everything looks.

The following markdown cheatsheet is adapted from: https://guides.github.com/features/mastering-markdown/

What is Markdown?

Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *.

Syntax guide

Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.

Admonitions

Admonitions are colorful blocks to highlight something and bring to immediate attention. Inspired from Docusaurus v2.

Usage:

::: followed by the type and closing with :::.

const Button = (props) => <button {...props} />

Headers

To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three (<h3>), use three number signs (e.g., ### My Header).

Alternate Syntax:

Alternatively, on the line below the text, add any number of == characters for heading level 1 or -- characters for heading level 2.

Emphasis

Strikethrough

Any word wrapped with two tildes (like ~~this~~) will appear crossed out.

Lists

Links

To create a link, enclose the link text in brackets [Wikipedia] and then follow it immediately with the URL in parentheses (https://wikipedia.com). [Wikipedia](https://wikipedia.com)

Wikipedia

You can optionally add a title for a link. This will appear as a tooltip when the user hovers over the link. To add a title, enclose it in parentheses after the URL. [Wikipedia](https://wikipedia.com "a free online encyclopedia")

Wikipedia

Images

Linking images is similar to creating links, by appending a ! in front of the link. ![Kitty Cat](http://placekitten.com/1280/800)

Code Blocks

Showcase samples of code with fenced code blocks and syntax highlighting. Additional support for Title, Line Numbers and Line Highlights using meta options.

Inline code

Inline code has back-ticks around it. Inline code can also be wrapped with links.

Basic Code block

There are two ways to create code block:

• Blocks of code are either fenced by lines with three back-ticks (```),
• or are indented with four spaces.

```
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["components/*"],
      "@/data/*": ["data/*"],
      "@/layouts/*": ["layouts/*"],
      "@/lib/*": ["lib/*"],
      "@/css/*": ["css/*"]
    }
  }
}
```

To add syntax highlighting, specify a language next to the back-ticks before the fenced code block.

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["components/*"],
      "@/data/*": ["data/*"],
      "@/layouts/*": ["layouts/*"],
      "@/lib/*": ["lib/*"],
      "@/css/*": ["css/*"]
    }
  }
}
```

With title

To show the file name, include the meta title="jsconfig.json"

```json title="jsconfig.json"
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["components/*"],
      "@/data/*": ["data/*"],
      "@/layouts/*": ["layouts/*"],
      "@/lib/*": ["lib/*"],
      "@/css/*": ["css/*"]
    }
  }
}
```

With title and line numbers:

To show line numbers, add the meta showLineNumbers.

```json title="jsconfig.json" showLineNumbers
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["components/*"],
      "@/data/*": ["data/*"],
      "@/layouts/*": ["layouts/*"],
      "@/lib/*": ["lib/*"],
      "@/css/*": ["css/*"]
    }
  }
}
```

Line numbers can be started at an arbitrary point as well using the meta showLineNumbers=n, where n = digits.

//```javascript title="rehype.js" showLineNumbers=65
const calculateStartingLine = (meta) => {
  const RE = /showLineNumbers=(?<lines>\d+)/i
  // pick the line number after = using a named capturing group
  if (RE.test(meta)) {
    const {
      groups: { lines },
    } = RE.exec(meta)
    return Number(lines)
  }
  return 0
}
//```

Line highlighting

Line highlighting can be done using the meta {n}.

• {2} - This will highlight line #2.
• {2,4,6} - This will highlight line #2, #4 and #6 only.
• {2-10} - This will highlight line #2 through #10 (inclusive).

```html title="sample.html" showLineNumbers {2,4,6}
<div>
  <h1>Code blocks and line highlighting</h1>
  <p>Use the meta property to enable features</p>
  <p>Highlighted lines are syntax colored</p>
</div>
```

Table

Tables aren't part of the core Markdown spec, but they are part of GFM.

Colons can be used to align columns.

| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |

There must be at least 3 dashes separating each header cell.
The outer pipes (|) are optional, and you don't need to make the
raw Markdown line up prettily. You can also use inline Markdown.

| Markdown | Less      | Pretty     |
| -------- | --------- | ---------- |
| _Still_  | `renders` | **nicely** |
| 1        | 2         | 3          |

Colons can be used to align columns.

There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.

Blockquotes

Blockquotes are very handy to showcase a phrase or a text said by another person. To start a blockquote, simply prefix with >. To have multiple blockquotes in the same container, keep adding a > on each line.

Blockquotes are very handy to showcase a phrase or a text said by another person. This line is part of the same quote.

This is a very long line that will still be quoted properly when it wraps. Oh, boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.

Collapsible Section

An accordion like element which can wrap more Markdown format content.

```
<Details>
  Title for the container

  More Content
</Details>
```

public class Order
{
    public int OrderId { get; set; }
    public int CustomerId { get; set; }

    public List<int> Products { get; set; }
}

Horizontal Rule

Three or more Hyphens ---, Asterisks ***, or Underscores ___ will render a <hr>.

===

Task Lists

- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item

• list syntax required (any unordered or ordered list supported)
• this is a complete item
• this is an incomplete item

Footnotes

Footnotes allow to add notes and references at the end of the document, like Wikipedia. When you create a footnote, a superscript number with a link appears where you added the footnote reference. Clicking on the link to jumps to the content of the footnote at the bottom of the page. To create a footnote reference, add a caret and an identifier inside brackets The Big Bang Theory[^1]

• First Footnote¹
• Second Footnote²
• Third Footnote³
• Random strings as the identifier[^@#$%]
• Footnotes with some URL in it⁴