Back to blog

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 文档。站内链接示例:博客列表。

写作建议:一个段落围绕一个问题展开,用标题组织长文章。

引用中也可以包含 强调文字 和 普通链接。

列表与任务列表

  • 说明问题的背景。
  • 给出可以复现的例子。
    • 补充必要的前提。
    • 解释结果与限制。
  1. 先完成文章正文。
  2. 再检查图片与链接。
  3. 最后确认发布状态。
  • 填写文章标题与摘要
  • 检查文章 slug 和发布状态
  • 完成发布前预览

任务列表在博客中用于展示状态,读者不能直接勾选修改。

表格与脚注

字段用途示例
slug决定文章地址hello-nuxt
draft控制文章是否出现在博客中true

脚注适合放补充说明或出处,不打断正文。1


图片与 MDC 属性

图片尺寸

下图复用项目已有的头像文件,指定显示宽度;点击图片可以查看放大效果。

本地图片放在 public/ 下,正文引用从 /images/… 开始,不包含 public。封面图片需要在 Frontmatter 的 image 中单独填写。

文字属性与数据绑定

这段文字独占一行,并留出下方间距。

这段文字使用博客的主题色。

当前文章标题来自 Frontmatter:博客写作示例:Markdown、MDC 与组件。

提示框

note:补充说明

笔记范围这是补充说明。提示框正文可以包含 加粗、行内代码、链接 和列表。
  • 说明适用范围。
  • 补充阅读前提。

tip:技巧与建议

写作技巧文章页会单独显示 Frontmatter 的标题和摘要,正文直接从二级标题开始即可。

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 行。

Hello.swift
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;
}

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

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。

Sources/Welcome.swift
let title = "Writing examples"
print(title)

标签页

tabs 与 tabs-item:切换正文内容

先写清文章的背景、过程与结论,再选择合适的组件辅助说明。

  • 短提示使用提示框。
  • 多种方案使用标签页。

折叠内容

collapsible:折叠补充说明

accordion 与 accordion-item:常见问题

卡片

card:单张链接卡片与命名插槽

查看所有文章

卡片的标题来自 #title 插槽,这段介绍来自 #default 插槽。

card-group:卡片网格

博客列表

阅读已发布的文章。

标签索引

按主题查找相关内容。

步骤

steps:带序号的教程步骤

通过 level 指定哪些标题作为步骤;这里使用四级标题。

准备文章

填写标题、摘要、日期与 slug。

编写正文

用 Markdown 组织章节,再按需要添加提示框、代码与图片。

检查效果

预览页面,检查目录跳转、组件交互与窄屏排版。

字段说明

field:单个参数

slug
string required
文章地址标识,例如 hello-nuxt。使用小写英文字母、数字与连字符。

field-group:一组参数

title
string required
文章原始标题。
tags
string[]
文章标签数组,例如 nuxt、vue、web。
draft
boolean
设为 true 时,文章不会出现在当前博客列表、详情查询与搜索中。

提示词

prompt:复制完整提示词

点击复制按钮获取下面的写作提示词。这个组件用于展示与复制内容,本身不会调用 AI。

请将文章整理成背景、步骤和结论,并检查标题层级、图片说明和站内链接。

从 Obsidian 迁移时的对应关系

Obsidian 内容博客中的对应方式
双链 [[笔记]]标准 Markdown 链接,目标使用文章的实际 URL
图片嵌入 ![[图片.png]]标准 Markdown 图片,引用 public/ 下的文件
Callout本文的提示框组件
可折叠 Calloutcollapsible 或 accordion
高亮文字MDC 文字属性,例如主题色样式
隐藏注释HTML 注释
笔记嵌入、块引用、Dataview当前没有自动转换或专用渲染
数学公式、Mermaid、Excalidraw当前没有配置专用渲染,可使用导出的图片

Obsidian 的 %%…%% 注释不会在博客中自动隐藏。迁移时,先核对内容与附件,再用本项目的实际页面预览确认效果。

Footnotes

  1. 本文按当前项目安装的组件编写;新增渲染插件后,可以继续补充示例。 ↩

© 2026 Kevin Guo's Blog. All rights reserved.