博客写作手册:可用功能一览

非常感谢@mizorewww提供的模板。 同时他也在我学习的路上提供了其他的许多帮助，再次致谢。

这篇文章既是写作手册,也是一份"能跑的示例":文中的每一段都对应博客支持的一种写作功能。你可以直接照抄语法,把它当成模板。

文本与排版

正文支持普通 Markdown 语法。可以用 加粗、斜体、删除线,以及 inline code。inline code 的主题在明亮和暗黑模式下都做了低对比度处理,不会从正文里突兀地跳出来。

引用块用 > 开头:

博客的写作语法刻意保持克制,只在需要嵌入富组件时才引入短语法。普通文章只管写 Markdown,构建阶段会把这些短语法转换成稳定的 MDX 组件或 Shiki 代码块。

有序列表:

1. 第一项
2. 第二项
   1. 嵌套项
   2. 另一个嵌套项
3. 第三项

无序列表:

• 用 - 或 * 都可以
• 支持 内部链接 和 外部链接,外部链接会自动带 target="_blank" 和 rel="noopener noreferrer"
• 也支持自动链接:https://example.com

标题层级

这里依次演示从 H2 到 H4 的层级(H1 留给文章标题)。目录(右侧 TOC)会自动从这些标题生成,并带锚点跳转。

H3:三级标题

正文内容。

H4:四级标题

正文内容。

代码块

代码块会自动获得标题栏:左侧语言图标,右侧复制按钮。如果代码块带了 title 元信息,标题栏会显示文件名。

type Post = {
  slug: string
  title: string
  date: string
  tags: string[]
}
 
function summarize(post: Post): string {
  return `${post.title} · ${post.date} · ${post.tags.join(', ')}`
}

带标题和行号的代码块:

export function pickLatest(posts: Post[]): Post[] {
  return [...posts].sort((a, b) => (a.date < b.date ? 1 : -1))
}

不同语言会自动切换图标和主题色:

yarn install
yarn dev

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

{
  "name": "blog",
  "version": "1.0.0",
  "private": true
}

图标 shortcode

行内图标用 :icon-名称: 语法,名称对应 Lucide 图标。例如:rocket 是 :icon-rocket:,代码是 :icon-code:,标签是 :icon-tag:。图标在构建期被替换成 <Icon> 组件,不会增加运行时开销。

常用图标::icon-book:、:icon-pencil:、:icon-link:、:icon-github:、:icon-bell:。

GitHub 代码引用

::github-code 短语法可以在文章里直接嵌入仓库中的真实代码,渲染后带 Shiki 高亮、语言图标和 GitHub 跳转链接。本站仓库默认指向 omicron0314/blog。

::github-code repo="omicron0314/blog" ref="HEAD" path="contentlayer.config.ts" lines="1-2" lang="ts" title="contentlayer.config.ts"

渲染效果:

export { Authors, Blog } from './contentlayer/config/documentTypes'
export { default } from './contentlayer/config/source'

再嵌入一段 lib/utils.ts 作为示例:

import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'
 
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

GitHub diff 引用

::github-diff 渲染某个 commit 或区间 diff,并按 GitHub 风格分行染色。

::github-diff repo="omicron0314/blog" ref="4d2b6dfb6cd6d6b6f8ef139988b2838fe335b8ff" path="css/tailwind.css" lines="1-20"

渲染效果:

No diff matched this query.

表格

表格会自动被 TableWrapper 包裹,在窄屏下可横向滚动。

图片

图片用普通 Markdown 图片语法即可,渲染时会自动套用 MDXImage,带 width/height 防 CLS。

也可以直接用 <Image> 组件,适合需要精确控制尺寸的场景。

行情图表

单行 ticker → Mini Chart

在单独一行写 $AAPL,渲染成 TradingView Mini Chart。注意:只有整段内容就是一个 ticker 时才会替换,正文里随手提到 $AAPL 不会触发。

$AAPL

渲染效果:

加密资产也支持:

Advanced Chart 短语法

::tv 后跟 symbol 和可选参数,渲染成完整的 TradingView Advanced Chart。

::tv AAPL interval=60 height=460

渲染效果:

支持的参数:

• interval:K 线周期(分钟数,如 60、240、D、W)
• height:图表高度(像素)
• locale:界面语言
• timezone:时区

Frontmatter 字段速查

文章头部的 YAML frontmatter 支持以下字段:

多语言关联

同篇文章的中文和英文版本通过 translationKey 关联。例如本文:

• content/blog/zh/blog-features-showcase.md
• content/blog/en/blog-features-showcase.md

两者使用相同的 translationKey: blog-features-showcase,语言切换器会自动跳转到对应版本。

写作建议

• 普通内容只用 Markdown,不要在正文里塞过多 JSX。
• 引用源码时优先用 ::github-code 而不是复制粘贴,这样代码会随仓库自动更新。
• 行情图表只在金融相关文章里用,避免在技术文里插入干扰阅读的 widget。
• 图片尽量给 width/height,博客的 MDXImage 已经默认做了,但自定义 <img> 时要留意 CLS。
• 文章头部日期用 YYYY-MM-DD,构建时会解析为 ISO 时间用于排序和 sitemap。

小结

这篇示例文章本身就是一份"能跑的文档":你看到的每一种渲染效果,对应源码里的一段语法。把这篇文章保存下来当模板,新文章直接复制改写就行。