MDX Syntax Guide - How to Write an Article

On this blog, you can write articles in MDX format. MDX combines Markdown with JSX, and in addition to the usual Markdown syntax, you can use custom components.

Basic Markdown Syntax

Headings

Headings use the number of # characters to indicate their hierarchy.

# Heading 1 (H1)
## Heading 2 (H2)
### Heading 3 (H3)
#### Heading 4 (H4)

ヒント

The article title is automatically displayed as H1, so we recommend starting your body from H2 (##).

Text Styling

**Bold** or __Bold__
*Italic* or _Italic_
~~Strikethrough~~
`Inline code`

Result: Bold, Italic, ~~Strikethrough~~, Inline code

Lists

Unordered Lists

- Item 1
- Item 2
  - Nested item
  - Nested item
- Item 3

Item 1
Item 2
- Nested item
- Nested item
Item 3

Ordered Lists

1. First item
2. Second item
3. Third item

First item
Second item
Third item

Links and Images

[Link text](https://example.com)
![Image description](/images/example.jpg)

Blockquotes

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

This is a quote. It can span multiple lines.

Code Blocks

You can specify a language to enable syntax highlighting.

```javascript
function hello() {
  console.log("Hello, World!");
}
```

function hello() {
  console.log("Hello, World!");
}

Tables

| Column 1 | Column 2 | Column 3 |
|-----|-----|-----|
| A   | B   | C   |
| D   | E   | F   |

Column 1	Column 2	Column 3
A	B	C
D	E	F

Horizontal Rule

---

Custom Components

In this blog, you can use the following custom components.

Callout

A component used to make important information stand out. There are 5 types.

<Callout type="info">
  This is an info callout.
</Callout>

<Callout type="tip">
  This is a tip callout with helpful advice.
</Callout>

<Callout type="warning">
  This is a warning callout for things that require caution.
</Callout>

<Callout type="error">
  This is an error callout for errors or dangerous operations.
</Callout>

<Callout type="success">
  This is a success callout for achievements or completed tasks.
</Callout>

情報

This is an info callout.

ヒント

This is a tip callout with helpful advice.

注意

This is a warning callout for things that require caution.

エラー

This is an error callout for errors or dangerous operations.

成功

This is a success callout for achievements or completed tasks.

You can also set a custom title:

<Callout type="info" title="Custom Title">
  This is a callout with a custom title.
</Callout>

Custom Title

This is a callout with a custom title.

Card

Displays information in a card format.

<Card title="Card Title" icon="📝">
  Write the card content here.
</Card>

📝

Card Title

Write the card content here.

You can also create cards with links:

<Card title="External Link" href="https://astro.build" icon="🚀">
  Click to jump to the link destination.
</Card>

🚀

External Link

Click to jump to the link destination.

CardGrid

Displays multiple cards in a grid.

<CardGrid cols={2}>
  <Card title="Card 1" icon="1️⃣">
    This is the first card.
  </Card>
  <Card title="Card 2" icon="2️⃣">
    This is the second card.
  </Card>
</CardGrid>

1️⃣

Card 1

This is the first card.

2️⃣

Card 2

This is the second card.

You can also display 3 columns with cols={3}:

⚡

Feature A

Fast processing

🔒

Feature B

Secure

🎨

Feature C

Beautiful UI

Steps

A component for explaining steps in order.

<Steps>
  <Step title="Create the project" step={1}>
    First, create a new project.
  </Step>
  <Step title="Install dependencies" step={2}>
    Install the necessary packages.
  </Step>
  <Step title="Start the development server" step={3}>
    Start the development server and check it.
  </Step>
</Steps>

Create the project

First, create a new project.

Install dependencies

Install the necessary packages.

Start the development server

Start the development server and check it.

Tabs

Switch and display content using tabs.

<Tabs items={["JavaScript", "TypeScript", "Python"]}>
  <TabPanel>
    This is an example of JavaScript code.
  </TabPanel>
  <TabPanel>
    This is an example of TypeScript code.
  </TabPanel>
  <TabPanel>
    This is an example of Python code.
  </TabPanel>
</Tabs>

function greet(name) {
  return `Hello, ${name}!`;
}

function greet(name: string): string {
  return `Hello, ${name}!`;
}

def greet(name):
    return f"Hello, {name}!"

Article Frontmatter

At the beginning of each article, write the following frontmatter:

---
title: 'Article title'
description: 'Article description (used for SEO)'
date: 2024-04-16
tags: ['tag1', 'tag2']
image: '/images/og-image.jpg'  # Optional: OGP image
draft: true  # Optional: set to draft mode
---

Frontmatter Fields

title: Article title (required)
description: Article description (required, used for SEO)
date: Publish date (required, YYYY-MM-DD format)
tags: Array of tags (optional)
image: Path to OGP image (optional)
draft: If set to true, it becomes draft mode (optional)

Importing Components

To use custom components in your article, add the import statements right after the frontmatter:

---
title: 'Article title'
---

import Callout from '@/components/mdx/Callout.astro';
import Card from '@/components/mdx/Card.astro';
import CardGrid from '@/components/mdx/CardGrid.astro';
import Steps from '@/components/mdx/Steps.astro';
import Step from '@/components/mdx/Step.astro';
import Tabs from '@/components/mdx/Tabs.astro';
import TabPanel from '@/components/mdx/TabPanel.astro';

Write the body here...

That’s the complete list of the syntax and components you can use in this blog. Combine them to create readable, beautiful articles.