September 6, 2026
博客写作示例:Markdown、MDC 与组件
当前博客支持的 Markdown 排版、MDC 属性和文章组件示例,按用途查找并参考对应写法
- nuxt
- vue
- web
这篇文章是本项目的写作示例。使用目录查找组件,查看实际效果,再打开 content/blog/hello-nuxt.md 参考对应写法。中英文界面都展示这同一份文章。
使用本文作为新文章模板时,可先将文件顶部的 draft 设为 true;准备公开后再改为 false。
组件速查
| 想展示的内容 | 组件或写法 | 本文位置 |
|---|---|---|
| 普通正文、列表、表格、脚注 | 标准 Markdown | 正文排版 |
| 图片、文字样式、数据绑定 | MDC 属性与绑定 | 图片与 MDC 属性 |
| 提示、技巧、警告、危险操作 | note、tip、warning、caution | 提示框 |
| 自定义颜色与图标的提示 | callout | 提示框 |
| 徽章、按键、图标、文件图标 | badge、kbd、icon、code-icon | 行内组件 |
| 代码标题、行高亮、多组代码、长代码 | 代码块、code-group、code-collapse | 代码展示 |
| 展示效果及对应代码、文件树 | code-preview、code-tree | 代码展示 |
| 内容标签页 | tabs、tabs-item | 标签页 |
| 折叠补充说明与常见问题 | collapsible、accordion、accordion-item | 折叠内容 |
| 单张链接卡片、卡片网格 | card、card-group | 卡片 |
| 分步骤教程 | steps | 步骤 |
| 参数与配置项 | field、field-group | 字段说明 |
| 可复制的提示词 | prompt | 提示词 |
正文排版
段落、强调与引用
段落之间空一行。可以使用 加粗强调、斜体补充、删除过时内容,以及 draft: true 这样的行内代码。
外部链接示例:Nuxt Content 文档。站内链接示例:博客列表。
写作建议:一个段落围绕一个问题展开,用标题组织长文章。
引用中也可以包含 强调文字 和 普通链接。
列表与任务列表
- 说明问题的背景。
- 给出可以复现的例子。
- 补充必要的前提。
- 解释结果与限制。
- 先完成文章正文。
- 再检查图片与链接。
- 最后确认发布状态。
- 填写文章标题与摘要
- 检查文章 slug 和发布状态
- 完成发布前预览
任务列表在博客中用于展示状态,读者不能直接勾选修改。
表格与脚注
| 字段 | 用途 | 示例 |
|---|---|---|
slug | 决定文章地址 | hello-nuxt |
draft | 控制文章是否出现在博客中 | true |
脚注适合放补充说明或出处,不打断正文。1
图片与 MDC 属性
图片尺寸
下图复用项目已有的头像文件,指定显示宽度;点击图片可以查看放大效果。
![]()
本地图片放在 public/ 下,正文引用从 /images/… 开始,不包含 public。封面图片需要在 Frontmatter 的 image 中单独填写。
文字属性与数据绑定
这段文字独占一行,并留出下方间距。
这段文字使用博客的主题色。
当前文章标题来自 Frontmatter:博客写作示例:Markdown、MDC 与组件。
提示框
note:补充说明
tip:技巧与建议
warning:注意事项
slug 会改变 URL。调整文章地址时,需要同时检查旧链接。caution:危险操作
callout:自定义颜色、图标与链接
callout 可用颜色:primary、secondary、neutral、info、success、warning、error。
行内组件
badge:徽章
文章状态: 写作示例。适合标记实验功能、版本或内容状态。
kbd:按键
快捷键示例::kbd{value="meta"} + K,或 + K。
icon:图标
主页 ,文章 ,标签 。
code-icon:文件类型图标
Swift 文件 。文件图标也会出现在带文件名的代码块中。
代码展示
代码块:标题与行高亮
这段代码显示文件名,并突出第 2 行。
let name = "Kevin"
let message = "Hello, \(name)!"
print(message)
代码块支持复制。常用高亮语言包括 c、cpp、python / py、javascript / js、typescript / ts、bash、zsh、rust / rs、markdown / md,以及 css、html、jsx、json、mdc、sh、shell、swift、tsx、vue、yaml。
常用语言图标
切换标签查看九种常用语言的图标与高亮。图标根据方括号中的标题或文件扩展名匹配,例如 Python 与 main.py 都显示 Python 图标。仅写代码语言、不填写标题时,不会显示文件标题栏。
#include <stdio.h>
int main(void) {
puts("Hello, blog!");
return 0;
}
#include <iostream>
int main() {
std::cout << "Hello, blog!\n";
return 0;
}
print("Hello, blog!")
console.log("Hello, blog!");
const message: string = "Hello, blog!";
console.log(message);
echo "Hello, blog!"
print -r -- "Hello, blog!"
fn main() {
println!("Hello, blog!");
}
# 写作笔记
使用 **加粗** 强调要点。
C 的 .c、.h 文件使用 C 图标;C++ 的 .cpp、.cc、.cxx、.hpp、.hh、.hxx 文件使用 C++ 图标。Bash 与 Zsh 使用同一套 Shell 高亮语法,当前配置均使用 GNU Bash 图标,包括 .sh、.zsh、.zshrc 和 .zprofile。
code-group:切换多组代码
切换标签,查看不同用途的命令。
pnpm dev
pnpm content:check
pnpm generate
code-collapse:展开长代码
title: 博客写作示例
description: 用于参考 Markdown 与 MDC 组件
slug: hello-nuxt
date: 2026-09-06
updated: 2026-10-11
tags:
- nuxt
- vue
- web
featured: false
draft: true
code-preview:展示效果与代码
上方是实际展示效果,下方是对应示例代码。#code 指定组件的代码插槽。
预览区域:这段文字使用加粗效果。
<strong>预览区域</strong>:这段文字使用加粗效果。
code-tree:按文件树浏览代码
选择文件查看代码。文件名中的 / 形成目录层级;默认打开 Sources/Welcome.swift。
let title = "Writing examples"
print(title)
标签页
tabs 与 tabs-item:切换正文内容
先写清文章的背景、过程与结论,再选择合适的组件辅助说明。
- 短提示使用提示框。
- 多种方案使用标签页。
检查标题、目录、代码块、图片和站内链接,再确认手机宽度下的排版。
将准备公开的文章设为 draft: false,并运行项目检查。
折叠内容
collapsible:折叠补充说明
适合放较长的背景、推导或可选阅读内容。
主线内容放在正文中,折叠区承载补充信息。
accordion 与 accordion-item:常见问题
Obsidian 的提示框语法与 MDC 不同。博客文章使用 note、tip、warning、caution 或 callout 组件。
可以。组件内容中可以使用 加粗、列表、链接,或嵌套其他组件。
卡片
card:单张链接卡片与命名插槽
card-group:卡片网格
步骤
steps:带序号的教程步骤
通过 level 指定哪些标题作为步骤;这里使用四级标题。
字段说明
field:单个参数
hello-nuxt。使用小写英文字母、数字与连字符。field-group:一组参数
nuxt、vue、web。true 时,文章不会出现在当前博客列表、详情查询与搜索中。提示词
prompt:复制完整提示词
点击复制按钮获取下面的写作提示词。这个组件用于展示与复制内容,本身不会调用 AI。
请将文章整理成背景、步骤和结论,并检查标题层级、图片说明和站内链接。
从 Obsidian 迁移时的对应关系
| Obsidian 内容 | 博客中的对应方式 |
|---|---|
双链 [[笔记]] | 标准 Markdown 链接,目标使用文章的实际 URL |
图片嵌入 ![[图片.png]] | 标准 Markdown 图片,引用 public/ 下的文件 |
| Callout | 本文的提示框组件 |
| 可折叠 Callout | collapsible 或 accordion |
| 高亮文字 | MDC 文字属性,例如主题色样式 |
| 隐藏注释 | HTML 注释 |
| 笔记嵌入、块引用、Dataview | 当前没有自动转换或专用渲染 |
| 数学公式、Mermaid、Excalidraw | 当前没有配置专用渲染,可使用导出的图片 |
Obsidian 的 %%…%% 注释不会在博客中自动隐藏。迁移时,先核对内容与附件,再用本项目的实际页面预览确认效果。
Footnotes
- 本文按当前项目安装的组件编写;新增渲染插件后,可以继续补充示例。 ↩