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.
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
- Sub-item
- 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
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}!`;
```
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 body1.
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.
:::
A regular note or supplementary information.
Recommendations, tips, and best practices.
Additional context or reference information.
An operation that requires care, or a pitfall.
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
:::
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.
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 .
Block
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
Matrices
$$
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)
---
9. Image Lightbox
Because this site has docusaurus-plugin-image-zoom enabled, clicking an image in the body opens it enlarged in a modal.
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 |  |
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.
12. Glossary tooltips (<Term>)
Wrapping a technical term in <Term> shows its definition from the glossary on hover and on keyboard focus. No import is needed (it is registered in src/theme/MDXComponents.tsx).
This class has low <Term id="cohesion">cohesion</Term>.
The id must match the {#id} written on a heading in the glossary page for the same locale (docs/glossary.md for Japanese, i18n/en/docusaurus-plugin-content-docs/current/glossary.md for English). If you write an id that is not in the glossary, no tooltip appears and only the link remains, and a VERIFY_LINKS=1 build reports it as a broken anchor.
Guidelines:
- Mark a term only at its first occurrence in a given article
- Do not put it inside headings, code blocks, or existing links
- Do not mark a term in the body of the very article the glossary points to (it would send the reader back to the page they are already on). A chapter's opening list of topics to come is the exception — there it helps to grasp the definition before reading
- The visible text is free-form, so inflected forms and other spellings are fine (
<Term id="cohesion">highly cohesive</Term>)
To add a term, put a ### Term name {#id} heading in the glossary page for that locale, with a one- or two-sentence definition paragraph directly beneath it. That first paragraph is what the tooltip shows, so keep links and lists in later paragraphs. The id must be lowercase letters, digits, and hyphens.
Related resources
- Docusaurus Markdown Features
- GitHub Flavored Markdown Spec
- Mermaid official documentation
- List of supported KaTeX functions