DeDeLab Blog Formatting Tutorial: Markdown and MDX Style Guide

Wed, 25 Feb 2026 00:00:00 GMT

This article is a live format playground. You can copy any snippet below and use it directly in your own post.

1) Minimum frontmatter you should always provide

Use this as your default template:

---
title: "Your Post Title"
description: "One sentence summary for card preview and SEO."
date: "2026-02-25"
category: "Blog"
tags: ["Tag1", "Tag2"]
featuredImage: "./cover.png"
pinned: false
---

Why these fields matter

title and description are used in post cards and SEO.
date controls sort order.
category is used for list grouping.
tags powers Topics pages.
featuredImage is used for list thumbnail and top cover.
pinned controls the pinned stories panel.

2) Core markdown blocks

Paragraph and inline code

Use inline code like npm run develop for commands and config keys.

Quote

Keep your writing practical, testable, and easy to copy.

List

Keep one point per bullet.
Prefer short lines for scanning.
Use examples whenever possible.

Divider

Add a divider between major sections:

---

3) Code blocks

This project supports Prism highlighting and line numbers.

export function createPostMeta() {
  return {
    category: "Blog",
    pinned: false,
  };
}

def normalize_tags(tags):
  return [tag.strip() for tag in tags if tag]

npm run develop
npm run build

4) Image and caption

Local image example:

Example cover from local asset

Figure 1. A local image referenced from the repository.

Remote image example also works:

Figure 2. A remote image URL.

5) Highlight and links

Use mark to emphasize key text.

Regular markdown link: Open the Gatsby docs

Raw HTML anchor also works:

Open MDX docs

6) MDX custom component: Alert

Use this for warnings, tips, and important notes.

Tip: keep your description under 160 characters for cleaner previews.

Avoid missing featuredImage, otherwise post cards may look broken.

If npm run build passes, your post format is valid.

Copy-ready snippet

<Alert severity="info">
  Put your message here.
</Alert>

7) MDX custom component: SpecialLink

Use this when you want a rich link card (video/demo/repo).

Copy-ready snippet

<SpecialLink
  href={"https://example.com"}
  title={"Card title"}
  description={"Card summary"}
  site={"example.com"}
  image={"https://example.com/cover.png"}
/>

8) Optional advanced layout with Box and Typography

You can also use MUI wrappers that are mapped in this project:

<Box sx={{ border: "1px solid", borderColor: "divider", borderRadius: "8px", p: 2, my: 2 }}>
  <Typography sx={{ fontWeight: 700 }}>
    Custom callout with Box + Typography
  </Typography>
  <Typography sx={{ color: "text.secondary" }}>
    Useful for custom layout blocks without creating a new React component.
  </Typography>
</Box>

9) Quick publishing checklist

Put your file in content/posts/<slug>/index.mdx.
Fill frontmatter fields first.
Verify featuredImage path exists.
Run npm run develop for preview.
Run npm run build before pushing.

If you follow this tutorial format, your post should render correctly in list pages, post detail pages, Topics, and pinned areas.

DeDeLab 博客格式教程：Markdown 与 MDX 写作示例

Wed, 25 Feb 2026 00:00:00 GMT

这是一篇“可复制”的格式演示文。你可以把下面任意片段直接粘贴到自己的 index.mdx 中使用。

1) 最小 frontmatter 模板

---
title: "文章标题"
description: "用于卡片摘要和 SEO 的一句话说明"
date: "2026-02-25"
category: "Blog"
tags: ["Tag1", "Tag2"]
featuredImage: "./cover.png"
pinned: false
locale: "zh"
translationKey: "same-post-key"
---

说明：

locale 控制语言（en / zh）。
translationKey 用于把同一篇文章的多语言版本关联起来。

2) 常用 Markdown

内容尽量短句、结构化，方便读者快速扫描。

列表一项
列表二项
列表三项

npm run develop 可用于本地预览。

3) 代码块

export const supportedLocales = ["en", "zh"];

npm run develop
npm run build

4) 图片与说明

本地图片示例

Figure 1. 本地资源图片。

5) 提示框组件 Alert

提示：建议 description 控制在 160 字以内。

<Alert severity="warning">
  Put your message here.
</Alert>

6) 外链卡片组件 SpecialLink

7) 发布前检查

放到 content/posts/<slug>/index.mdx
frontmatter 填完整
执行 npm run build
确认页面在 /zh/<slug>/ 可访问

DeDeLab RSS Feed

DeDeLab Blog Formatting Tutorial: Markdown and MDX Style Guide

1) Minimum frontmatter you should always provide

Why these fields matter

2) Core markdown blocks

Paragraph and inline code

Quote

List

Divider

3) Code blocks

4) Image and caption

5) Highlight and links

6) MDX custom component: Alert

Copy-ready snippet

7) MDX custom component: SpecialLink

Copy-ready snippet

8) Optional advanced layout with Box and Typography

9) Quick publishing checklist

DeDeLab 博客格式教程：Markdown 与 MDX 写作示例

1) 最小 frontmatter 模板

2) 常用 Markdown

3) 代码块

4) 图片与说明

5) 提示框组件 Alert

6) 外链卡片组件 SpecialLink

7) 发布前检查