Markdown 教程写作规范:代码块、提示框与资源联动示例
演示教程文章支持的 Frontmatter 字段、提示框语法、表格排版,以及如何在文末自动关联「拾集」里的工具卡片。
#Frontmatter 字段说明
每篇教程开头的 --- 区域用于描述文章信息:
| 字段 | 是否必填 | 说明 |
|---|---|---|
title | 必填 | 文章主标题 |
slug | 选填 | 决定访问路径 /posts/<slug>/,省略时使用文件名 |
summary | 必填 | 显示在博客首页卡片上的摘要说明 |
date | 必填 | 发布日期,格式为 YYYY-MM-DD |
category | 必填 | 教程分类,用于首页左侧分类导航 |
tags | 选填 | 标签列表,支持首页多标签交集筛选 |
resources | 选填 | 关联 data/resources.json 中的资源 id 列表 |
resourceFilter | 选填 | 文末「去拾集浏览更多」按钮跳转的筛选参数 |
draft | 选填 | 设为 true 时,默认构建不会输出到 dist/ |
#正文常用排版语法
#提示框(Callouts)
写教程时,可以用提示框突出重点或避坑提醒:
#代码块与一键复制
使用三个反引号并标明语言(如 js、powershell、json),阅读页会自动生成语言标签与右上角复制按钮:
{
"title": "教程标题",
"category": "写作指南",
"resources": ["obsidian", "drawio"]
}#与「拾集」页面联动
文章末尾的「本文关联工具」区域会根据 Frontmatter 中的 resources 自动从 data/resources.json 读取名称、简介和直达链接。如果你想从零整理自己的知识库,推荐搭配下方列出的效率工具一起使用。