MDX Syntax Reference for nisshi.dev

MDX Syntax Reference for nisshi.dev

nisshi-dev
nisshi-dev

This page is auto-generated by Claude Code Agent Skills (Claude Opus 4.5) based on the implemented source code, then reviewed and edited by the author (nisshi-dev) before publication.

The nisshi.dev blog is written in MDX syntax. It's based on fumadocs-mdx v14.2.4, with some custom components added.

www.fumadocs.dev

This page introduces the available MDX syntax and components.


Basic Markdown Syntax

Headings

## Heading 2
### Heading 3
#### Heading 4

Text Formatting

**Bold text**
*Italic text*
~~Strikethrough~~
`Inline code`

Bold text, Italic text, Strikethrough, Inline code

Lists

- Bullet point 1
- Bullet point 2
  - Nested item

1. Numbered list 1
2. Numbered list 2
  • Bullet point 1
  • Bullet point 2
    • Nested item
  1. Numbered list 1
  2. Numbered list 2

Blockquotes

> This is a blockquote.
> It can span multiple lines.

This is a blockquote. It can span multiple lines.

External and internal links are displayed differently. External links automatically show an icon (↗) indicating the destination is an external site.

[Google](https://google.com)

Google

[Blog List](/blog)

Blog List


Code Blocks

Basic

```js
console.log('Hello World');
```
console.log('Hello World');

With Filename

You can display a filename using the title option.

```typescript title="src/components/Button.tsx"
export function Button({ onClick }: { onClick: () => void }) {
  return <button onClick={onClick}>Click me</button>;
}
```
src/components/Button.tsx
export function Button({ onClick }: { onClick: () => void }) {
  return <button onClick={onClick}>Click me</button>;
}

Line Numbers

You can display line numbers using the lineNumbers option. You can also specify the starting line number.

```js lineNumbers
function hello() {
  console.log("Hello");
}
```

```js lineNumbers=10
// Starting from line 10
function world() {
  console.log("World");
}
```
function hello() {
  console.log("Hello");
}
// Starting from line 10
function world() {
  console.log("World");
}

Line Highlighting

You can highlight specific lines using Shiki transformers.

```js
const highlighted = true; 
const normal = true;
```
const highlighted = true; 
const normal = true;

Diff Display

You can visually display added and removed lines.

```js
console.log("Hello"); 
console.log("World"); 
```
console.log("Hello"); 
console.log("World"); 

Syntax Highlighting

main.py
def hello_world():
    print("Hello, World!")

hello_world()
Terminal
npm install my-package
package.json
{
  "name": "my-project",
  "version": "1.0.0"
}

Package Installation

Displays with switchable tabs for npm/yarn/pnpm/bun.

```package-install
my-package
```
npm install fumadocs-ui

TypeScript ⇔ JavaScript Conversion

You can display switchable code using the ts2js option.

```tsx ts2js
import { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
  return <div>{children}</div>;
}
```
import { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
  return <div>{children}</div>;
}

Tabbed Code Blocks

You can display multiple code blocks as tabs using the tab option.

```ts tab="TypeScript"
const message: string = "Hello";
```

```js tab="JavaScript"
const message = "Hello";
```
const message: string = "Hello";

Callouts

You can create callout blocks using the :::type syntax.

TypePurpose
infoSupplementary information (default)
warning / warnWarnings and cautions
errorErrors and critical warnings
successSuccess and completion messages
ideaIdeas and hints

With Custom Title

You can set a custom title using the :::type[title] syntax.

:::info[Additional Info]
This is supplementary information with a custom title.
:::

:::info
This is supplementary information.
:::

:::warning
This is a warning message.
:::

:::error
This is an error message.
:::

:::success
This is a success message.
:::

:::idea
This is an idea or hint.
:::

Additional Info

This is supplementary information with a custom title.

This is supplementary information.

This is a warning message.

This is an error message.

This is a success message.

This is an idea or hint.


Cards

Displays links to related pages in card format.

<Cards>
  <Card title="Learn about Next.js" href="https://nextjs.org/docs" />
  <Card title="Learn about Fumadocs" href="https://fumadocs.dev" />
</Cards>

With Descriptions

<Cards>
  <Card href="https://nextjs.org/docs" title="Data Fetching">
    Learn about data fetching methods in Next.js
  </Card>
  <Card title="href is optional">
    You can create description cards without links
  </Card>
</Cards>

Data Fetching

Learn about data fetching methods in Next.js

href is optional

You can create description cards without links


nisshi.dev Custom Implementation

This component is custom-built for nisshi.dev. It automatically fetches OGP information and displays a link card.

When you write a URL on a single line, it automatically becomes an OGP-enabled link card.

https://nextjs.org

https://fumadocs.dev

https://github.com/honojs/hono
nextjs.org
fumadocs.dev
github.com

Manual Specification

You can also manually specify using the LinkCard component.

PropTypeRequiredDescription
urlstringDestination URL
titlestring-Title (skips OGP fetching when specified)
descriptionstring-Description text
imagestring-Image URL
<LinkCard
  url="https://example.com"
  title="Site Title"
  description="Site description"
/>

Math (KaTeX)

You can write mathematical formulas using LaTeX syntax.

Inline

Pythagorean theorem: $$c = \pm\sqrt{a^2 + b^2}$$

Pythagorean theorem: c=±a2+b2c = \pm\sqrt{a^2 + b^2}

Block

```math
E = mc^2
```
E=mc2E = mc^2
```math
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
```
ex2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

Media Embedding

Images

nisshi.dev Custom Implementation

Images can be enlarged by clicking. Uses react-medium-image-zoom.

github.com
![Sample image](https://pbs.twimg.com/media/G0Hwhu-bUAEbQBC?format=jpg&name=small)

Figure (Image with Caption)

nisshi.dev Custom Implementation

This component is custom-built for nisshi.dev.

A component for adding captions to images and other elements.

PropTypeRequiredDescription
captionstringCaption (description text)
childrenReactNodeChild elements (images, etc.)
classNamestring-Custom class name
<Figure caption="Event venue">
  ![Venue photo](./venue.jpg)
</Figure>

Video

nisshi.dev Custom Implementation

This component is custom-built for nisshi.dev. For WebM format, it automatically adds an MP4 fallback. Uses media-chrome.

github.com

A video player component.

PropTypeRequiredDescription
srcstringVideo URL
fallbackSrcstring-Fallback video URL
altstring-Alt text (for accessibility)
posterstring-Poster image URL
autoPlayboolean-Autoplay (default: false)
loopboolean-Loop playback (default: false)
mutedboolean-Muted (default: false)
childrenReactNode-Caption
<Video src="/content/blog/example/video.webm" alt="Demo video playback">
  Video description text
</Video>

Model3D (3D Models)

nisshi.dev Custom Implementation

This component is custom-built for nisshi.dev. Uses React Three Fiber and Drei.

github.com
github.com

Displays GLB/GLTF format 3D models. You can rotate, zoom, and pan using OrbitControls.

PropTypeRequiredDescription
srcstringModel file path
altstring-Model description (for accessibility)
childrenReactNode-Caption
heightstring | number-Viewer height (default: "400px")
autoRotateboolean-Auto-rotation (default: false)
autoRotateSpeednumber-Auto-rotation speed (default: 1.0)
scalenumber-Model scale (default: 1)
<Model3D src="/models/robot.glb" alt="Robot model" autoRotate>
  3D robot model (drag to rotate, scroll to zoom)
</Model3D>

YouTube Videos

nisshi.dev Custom Implementation

This component is custom-built for nisshi.dev. Uses @next/third-parties/google.

github.com

When you write a YouTube URL on a single line, it becomes an embedded player.

https://www.youtube.com/watch?v=Vxtr-JzaePY

X (Twitter) Posts

nisshi.dev Custom Implementation

This component is custom-built for nisshi.dev. Uses react-tweet.

github.com

X post URLs display as embedded tweets.

https://x.com/nisshi_dev/status/1697919798217200076

MediaGrid

nisshi.dev Custom Implementation

This component is custom-built for nisshi.dev.

A grid component for arranging media elements side by side. It supports various elements including images, Tweets, YouTube, and LinkCards.

PropTypeRequiredDescription
cols / columns2 | 3 | 4-Number of columns (default: 2)
gap"sm" | "md" | "lg"-Gap between elements (default: "md")
align"start" | "center"-Vertical alignment (default: "start")
childrenReactNodeChild elements
<MediaGrid cols={2}>
  ![Image 1](./image1.jpg)
  ![Image 2](./image2.jpg)
</MediaGrid>

<MediaGrid cols={3} gap="sm">
  ![Image 1](./image1.jpg)
  ![Image 2](./image2.jpg)
  ![Image 3](./image3.jpg)
</MediaGrid>

Combining with Figure

<MediaGrid>
  <Figure caption="Physical venue">
    ![Physical](./real.jpg)
  </Figure>
  <Figure caption="VR venue">
    ![VR](./vr.jpg)
  </Figure>
</MediaGrid>

Mermaid (Diagrams)

nisshi.dev Custom Implementation

This component is custom-built for nisshi.dev. Uses mermaid.

github.com

You can create flowcharts and diagrams using Mermaid syntax.

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

Sequence Diagram


Tables

| Feature | Description | Status |
|---------|-------------|--------|
| MDX | Extended Markdown syntax | ✅ |
| Syntax Highlighting | Code coloring | ✅ |
| Math | KaTeX formula display | ✅ |
FeatureDescriptionStatus
MDXExtended Markdown syntax
Syntax HighlightingCode coloring
MathKaTeX formula display

Frontmatter (Article Metadata)

Write metadata at the beginning of each article.

---
title: Article Title
description: Article description (used for SEO and OGP)
type: tech  # tech or idea
topics: ["Next.js", "React"]  # Tags
createdAt: 2025-01-01
published: true
featured: false  # Featured article
---

References


This page will be updated as new components are added. If you have ideas like "How about adding this component?", feel free to let me know in the comments below!

nisshi-dev
nisshi-dev

VRが好きなWebエンジニア。WebXRやVR・機械加工などの技術が好きでものづくりしている。WebXR JPというコミュニティやWeb技術集会というVR空間内の技術イベントを運営中。

Comments

Feel free to share your thoughts or questions about this article

Nickname:
Anonymous

Leave comment