Markdown syntax reference

A reference summarizing the Markdown and Docusaurus extended syntax usable on this site. Each syntax sample is shown alongside its rendered result.

How to use this page

Use it as a cheat sheet for those moments while writing when you think, "wait, how did that syntax go again?" You can copy and paste the samples directly.

1. Basic Markdown

Headings

# H1
## H2
### H3
#### H4
##### H5
###### H6

H1 overlaps with the page title (the frontmatter title), so in the body it is standard to start from ## H2.

Paragraphs and line breaks

Paragraph 1

Paragraph 2 (separated by a blank line)

Two trailing spaces force a  
hard line break (not recommended; using `<br />` makes the intent clearer)

Emphasis

**bold** *italic* ~~strikethrough~~ `inline code`

bold italic ~~strikethrough~~ inline code

Lists

- Unordered list
- Can be nested
  - Sub-item
  - Sub-item
- Back

1. Ordered list
2. Numbers are auto-incremented, so it is OK to write them all as `1.`
3. Nesting is possible too
   1. Sub-item
   2. Sub-item

- [x] Task list (done)
- [ ] Task list (not done)

Unordered list
Can be nested
- Sub-item
- Sub-item
Back

Ordered list
Numbers are auto-incremented, so it is OK to write them all as 1.
Nesting is possible too
1. Sub-item
2. Sub-item

Task list (done)
Task list (not done)

Links

[Docusaurus official](https://docusaurus.io/)
[Relative link (within this site)](./intro.md)
[Anchor link (same page)](#headings)
<https://example.com> (writing a URL directly creates an automatic link)

Images

![alt text](/img/sample.png)
![alt text + title](/img/sample.png "Title shown on hover")

Because the .markdown img selector applies, images automatically open in a Lightbox when clicked. To disable the Lightbox for a specific image, add class="no-zoom" like <img class="no-zoom" src="..." />.

Code blocks

Basic

```typescript
const greeting: string = 'Hello, world!';
console.log(greeting);
```

const greeting: string = 'Hello, world!';
console.log(greeting);

File name (title)

```typescript title="src/utils/greet.ts"
export const greet = (name: string) => `Hello, ${name}!`;
```

src/utils/greet.ts
export const greet = (name: string) => `Hello, ${name}!`;

Line highlighting

```typescript {2,4-5}
const a = 1;
const b = 2;          // highlighted
const c = 3;
const d = 4;          // highlighted
const e = 5;          // highlighted
```

const a = 1;
const b = 2;
const c = 3;
const d = 4;
const e = 5;

Line numbers

```typescript showLineNumbers
function add(a: number, b: number) {
  return a + b;
}
```

function add(a: number, b: number) {
  return a + b;
}

Tables

| Header A | Header B | Header C |
| --- | :---: | ---: |
| Left-aligned | Centered | Right-aligned |
| Data | Data | Data |

Header A	Header B	Header C
Left-aligned	Centered	Right-aligned
Data	Data	Data

Blockquotes

> A single-line quote

> A multi-line
> quote works too
>
> > Nesting works as well

A single-line quote

A multi-line quote works too

Nesting works as well

Horizontal rule

---

Footnotes

Add a footnote in the body[^memo].

[^memo]: Footnote content is collected and shown at the bottom of the page.

Add a footnote in the body¹.

2. Docusaurus Admonitions (recommended)

On this site, to emphasize the type of information, we recommend using Docusaurus admonitions. They start with :::type Title and end with :::.

The five admonition types

:::note[Note]
A regular note or supplementary information.
:::

:::tip[Helpful info]
Recommendations, tips, and best practices.
:::

:::info[Info]
Additional context or reference information.
:::

:::warning[Caution]
An operation that requires care, or a pitfall.
:::

:::danger[Critical warning]
An important warning related to data loss or security.
:::

Note

A regular note or supplementary information.

Helpful info

Recommendations, tips, and best practices.

Info

Additional context or reference information.

Caution

An operation that requires care, or a pitfall.

Critical warning

An important warning related to data loss or security.

Using other Markdown inside an admonition

:::tip[Example with code]
You can use **bold** and `inline code` inside a list too.

```typescript
const example = 'Code blocks work inside admonitions too';
```

- List
- works
- too
:::

Example with code

You can use bold and inline code inside a list too.

const example = 'Code blocks work inside admonitions too';

List
works
too

3. GitHub Alerts style (reference)

It is handy to know the > [!NOTE] Alerts format used on GitHub.com as a way of writing.

> [!NOTE]
> This is a note.

> [!TIP]
> This is a helpful tip.

> [!IMPORTANT]
> This is important information.

> [!WARNING]
> This is a warning.

> [!CAUTION]
> This is a critical caution.

Rendering in Docusaurus

By default, Docusaurus renders the > [!NOTE] format as a regular blockquote. To get the same styling as GitHub, you need to add the remark-github-blockquote-alert plugin.

On this site we recommend using Docusaurus admonitions such as :::note (see §2 above).

4. Mermaid diagrams

Because @docusaurus/theme-mermaid is enabled, setting a code block's language to mermaid renders it as a diagram.

Flowchart

```mermaid
graph LR
  A[Start] --> B{Condition}
  B -->|Yes| C[Process 1]
  B -->|No| D[Process 2]
  C --> E[End]
  D --> E
```

Sequence diagram

```mermaid
sequenceDiagram
  participant U as User
  participant F as Frontend
  participant B as Backend
  U->>F: Submit form
  F->>B: API request
  B-->>F: 200 OK
  F-->>U: Show success
```

Mind map

```mermaid
mindmap
  root((Tech publishing))
    Blog
      Weekly
      Monthly
    Documentation
      Guides
      Reference
    Social
      X
      Zenn
```

ER diagrams / class diagrams / Gantt charts

erDiagram, classDiagram, and gantt are supported in the same way. For details, see the Mermaid official documentation.

5. KaTeX math

With remark-math + rehype-katex, you can render math written in LaTeX syntax.

Inline

You can embed it in the body like $E = mc^2$.

You can embed it in the body like $E = mc^2$ .

Block

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}

Matrices

$$
A = \begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
$$

A = \begin{pmatrix} a & b \\ c & d \end{pmatrix}

6. Tabs

Importing the components at the top of a .md file lets you embed tab switching (it is MDX under the hood).

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="ts" label="TypeScript" default>

  ```typescript
  const greet = (name: string) => `Hello, ${name}`;
  ```

  </TabItem>
  <TabItem value="js" label="JavaScript">

  ```javascript
  const greet = (name) => `Hello, ${name}`;
  ```

  </TabItem>
</Tabs>

TypeScript
JavaScript

const greet = (name: string) => `Hello, ${name}`;

const greet = (name) => `Hello, ${name}`;

7. Details (collapsible)

You can collapse long information or supplementary notes.

<details>
  <summary>Click to show details</summary>

  Here you can write long explanations, code samples, tables, and so on.

  ```typescript
  const hidden = 'detail content';
  ```

</details>

Click to show details

Here you can write long explanations, code samples, tables, and so on.

const hidden = 'detail content';

8. Frontmatter

Written in YAML format at the top of each page. Docusaurus reads title / description / tags and reflects them in the HTML head tags and the sidebar.

For docs pages

---
sidebar_position: 1                # Display order within the sidebar
title: Page title                  # Page h1 + HTML title
description: Meta description      # For SEO (og:description)
tags: [tag1, tag2]
slug: /custom-path                 # Override the URL (optional)
hide_title: true                   # Hide the h1 (optional)
hide_table_of_contents: true       # Hide the right-hand TOC (optional)
toc_min_heading_level: 2           # Minimum TOC level (optional)
toc_max_heading_level: 4           # Maximum TOC level (optional)
---

For blog posts

---
slug: my-post                      # The end of the URL
title: Post title
authors: [rasshii]                 # A key defined in blog/authors.yml
tags: [tag1, tag2]
date: 2026-04-29                   # Publish date
draft: false                       # true to keep it unpublished
unlisted: false                    # true to exclude from lists, sitemap, and feed (direct URL access is still allowed)
---

Because this site has docusaurus-plugin-image-zoom enabled, clicking an image in the body opens it enlarged in a modal.

![Sample](/img/sample.png)

To exclude a specific image from the Lightbox, specify class="no-zoom" with an <img> tag:

<img src="/img/icon.svg" alt="Icon" class="no-zoom" />

10. Internal links and relative paths

The site is published under the site root. Use the following patterns for links and image references as appropriate.

Use case	Recommended	Example
Link between documents	Relative path	`[Another page](./naming.md)`
Link between blog posts	Relative path	`[Another post](./2026-04-29-welcome.md)`
Link to the top	Absolute from the site root	`[Top](/)` (in Docusaurus the URL path is linked as-is, left unprocessed; this works on this site because baseUrl is `/`)
Image (static/)	Absolute from the site root	`![](/img/sample.png)`

11. React components in the body (MDX)

Even in .md files you can use import statements and JSX (because they are processed as MDX).

import Highlight from '@site/src/components/Highlight';

<Highlight color="#8FB39A">This is a highlighted string</Highlight>

To implement it, prepare a React component such as src/components/Highlight.tsx.

Footnote content is collected and shown at the bottom of the page. ↩

1. Basic Markdown​

Headings​

Paragraphs and line breaks​

Emphasis​

Lists​

Links​

Images​

Code blocks​

Basic​

File name (title)​

Line highlighting​

Line numbers​

Tables​

Blockquotes​

Horizontal rule​

Footnotes​

2. Docusaurus Admonitions (recommended)​

The five admonition types​

Using other Markdown inside an admonition​

3. GitHub Alerts style (reference)​

4. Mermaid diagrams​

Flowchart​

Sequence diagram​

Mind map​

ER diagrams / class diagrams / Gantt charts​

5. KaTeX math​

Inline​

Block​

Matrices​

6. Tabs​

7. Details (collapsible)​

8. Frontmatter​

For docs pages​

For blog posts​

9. Image Lightbox​

10. Internal links and relative paths​

11. React components in the body (MDX)​

Related resources​

Footnotes​

1. Basic Markdown

Headings

Paragraphs and line breaks

Emphasis

Lists

Links

Images

Code blocks

Basic

File name (title)

Line highlighting

Line numbers

Tables

Blockquotes

Horizontal rule

Footnotes

2. Docusaurus Admonitions (recommended)

The five admonition types

Using other Markdown inside an admonition

3. GitHub Alerts style (reference)

4. Mermaid diagrams

Flowchart

Sequence diagram

Mind map

ER diagrams / class diagrams / Gantt charts

5. KaTeX math

Inline

Block

Matrices

6. Tabs

7. Details (collapsible)

8. Frontmatter

For docs pages

For blog posts

9. Image Lightbox

10. Internal links and relative paths

11. React components in the body (MDX)

Related resources

Footnotes