Markdown / MDX Writing Guide

This guide covers common Markdown syntax, Expressive Code integration in Astro Plain, GitHub-style alert blocks, and how to use MDX components from Starlight.

Reading time: 8 min
By:
Luka
Examples
AstroMDXMarkdownExpressive CodeGuide

NOTE

This article was translated using AI.

Common Markdown Syntax

Headings

Markdown uses # through ###### to represent heading levels 1~6:

Heading 1 (H1)

Heading 2 (H2)

Heading 3 (H3)

Heading 4 (H4)

Heading 5 (H5)
Heading 6 (H6)

Text Formatting

PreviewMarkdown
Bold text**bold text** or __bold text__
Italic text*italic text* or _italic text_
Bold and italic***bold and italic***
Strikethrough~~strikethrough~~
Inline code`inline code`
Ctrl + C<kbd>Ctrl</kbd> + <kbd>C</kbd>

Blockquotes and Nested Quotes

This is a basic blockquote.

This is a nested second-level blockquote.

Blockquotes also support bold and inline code.

Lists and Task Lists

Unordered list:

  • Item one
    • Sub-item A
    • Sub-item B
  • Item two

Ordered list:

  1. Phase 1: Environment setup
  2. Phase 2: Development and build
  3. Phase 3: Deployment and release

Task Lists:

  • Core feature design completed
  • Static multilingual routing and i18n
  • Documentation improvements in progress

Tables and Alignment

Left-aligned HeaderCenter-aligned HeaderRight-aligned Header
AstroSSG / SSRFast loading
Expressive CodeSyntax highlightingMulti-theme support
PagefindFull-text searchStatic site support

TIP

Using Astro’s Image or Picture components in MDX documents lets you take advantage of Astro’s image optimization features, such as automatic resizing, format conversion, and lazy loading.

Cover image

GitHub-Style Alert Blocks (BlockquoteAlerts)

Based on remark-github-blockquote-alert (opens in a new tab), you can use the > [!TYPE] syntax to create different types of alert blocks:

NOTE

For recording general background, context, or supplementary knowledge.

TIP

Provides tips that help improve development efficiency or user experience.

IMPORTANT

Highlights critical information that users must know or cannot overlook.

WARNING

Warns about issues that may cause build failures or unexpected behavior.

CAUTION

Alerts about serious risks that could lead to data loss or security vulnerabilities.

Footnotes

This is a sentence with a footnote1.

Footnotes can also span multiple lines2.

Code Highlighting

This project uses Expressive Code (opens in a new tab) for syntax highlighting.

Code Block Title

Add title="..." to the code block meta to render a title at the top of the block:

src/utils/math.ts
export function calculateSum(a: number, b: number): number {
  return a + b;
}

Line Numbers and Line Highlighting

Use showLineNumbers to enable line numbers, and {line range} to highlight specific lines:

src/services/api.ts
export async function fetchData(endpoint: string) {
  const url = `https://api.example.com/${endpoint}`;
  try {
    const response = await fetch(url);
    const data = await response.json();
    return data;
  } catch (error) {
    console.error("Fetch failed:", error);
    throw error;
  }
}

Diff and Insertion/Deletion Markers

Use ins={...} and del={...} to mark added or removed lines:

package.json
{
  "name": "my-astro-blog",
  "version": "1.0.0",
  "version": "2.0.0"
}

Or use a diff code block:

git diff site.config.ts
export default {
  allowRobots: false,
  allowRobots: true,
  postsPerPage: 10,
};

Text Highlighting

Use ins="text", del="text", or "keyword" to highlight specific text within a code block:

app.js
const express = require("express");
const app = express();
const port = 3000;


app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

Code Collapsing

Use collapse={start-end} to collapse a range of lines by default for long code blocks:

long-script.ts
import { defineCollection, z } from "astro:content";
7 collapsed lines


// Schema with many field definitions
const baseSchema = z.object({
  id: z.string(),
  createdTime: z.date(),
  updatedTime: z.date(),
  status: z.enum(["draft", "published", "archived"]),
});


export const collections = {
  posts: defineCollection({ schema: baseSchema }),
};

Terminal Style

Use frame="terminal" to render a code block as a terminal window with a title bar and control buttons:

Install and start
# Clone the template repository
git clone https://github.com/Aaakul/astro-plain.git my-blog


# Enter the directory and install dependencies
cd my-blog
pnpm install


# Start the local development server
pnpm dev

Built-in MDX Components

In .mdx files, the following components are globally registered and can be used without manual imports.

Steps Component

<Steps> is used for writing step-by-step guides, automatically numbering each step. It supports nested paragraphs, code blocks, and tabs.

Basic Usage

  1. Step 1: Clone the repository to your local machine.
  2. Step 2: Install dependencies in the project root directory.
  3. Step 3: Run the dev command to start live preview.

Combined Usage

  1. Edit the configuration file

    Edit site.config.ts in the project root directory:

    site.config.ts
    export default {
      siteUrl: "https://example.com",
      defaultLanguage: "en-US",
    };

  2. Install dependencies

    Choose the package manager you prefer:

    Terminal window
    bun install

  3. Start the development server

    Once the development server starts, the terminal will display the access URL or port. Open it in your browser to preview.

File Tree Component

<FileTree> generates a directory tree with hierarchical indentation and file type icons.

Features:

  • Directory indicator: Append a slash / to the name (e.g., src/) to mark it as a directory.
  • Highlight specific files/directories: Use bold syntax **filename**.
  • End-of-line description: Add a space and description text after the filename.
  • Ellipsis placeholder: Use ... to represent omitted files.
  • Directoryi18n/
    • …
    • Directorymessages/ Translation dictionaries for each language
      • zh-Hans.ts Chinese dictionary
      • en-US.ts English dictionary
      • ja-JP.ts Japanese dictionary
  • Directorysrc/content/
    • Directoryblog/ Blog posts (linked via translationKey)
      • …
    • Directoryauthor/ Author information (organized by language folder)
      • …
    • Directoryproject/ Project introductions (organized by language folder)
      • …
    • Directorymdx/ Other MDX content (organized by language folder)
      • Directory[lang]/
        • hero.mdx Hero section
  • site.config.ts Site core configuration file
  • …

Tabs Component

<Tabs> and <TabItem> organize different versions or related options of the same content into tabs.

Icons and Cross-Component Sync (syncKey)

<Tabs> components sharing the same syncKey will share the current selection. When the user switches tabs in one, all others with the same syncKey update in sync.

Terminal window
  bun --bun run dev
Terminal window
bun install
 
<Tabs syncKey="pkg-manager">
  <TabItem label="Bun" icon="bun">
    ```bash
      bun --bun run dev
    ```


  </TabItem>
15 collapsed lines


  <TabItem label="pnpm" icon="pnpm">
    ```bash
    pnpm run dev
    ```


  </TabItem>


  <TabItem label="npm" icon="npm">
    ```bash
    npm run dev
    ```


  </TabItem>
</Tabs>

Footnotes

  1. This is the content of a single-line footnote. ↩

  2. This is the first line of a multi-line footnote. This is the second line of the multi-line footnote. ↩

Last modified:

Related Posts

Last modified:

Astro Plain Usage Guide

Examples
AstroFrontendBlogTemplateGuide

Astro Plain is a minimalist multilingual static blog template built on Astro, with no CSS / UI framework dependencies. This article includes an introduction to Astro Plain features, configuration instructions, content management, and deployment guides.

Last modified:

Internationalization Guide

Examples
Astroi18nInternationalizationGuide

A guide to i18n in Astro Plain: how to use translation functions and add new languages.