写作样式手册：一篇文章能用到的全部写法

#新建一篇文章

在 content/archive/ 的某个文件夹下新建文件，文件名就是网址的最后一段（建议用英文和数字）：

content/archive/logs/2026-10-03-first-post.mdx
→ https://blog.princival.com/archive/logs/2026-10-03-first-post

这些路径相对独立的 blog-content 内容仓库，不是网站代码仓库。可复用的技术经验放在 content/archive/notes/，按时间记录的开发进展放在 logs/，未来计划放在 schedule/。从工作材料整理成文章的过程见这篇经验笔记。

文件开头是 frontmatter，用两行 --- 包住：

---
title: 文章标题              # 必填
date: 2026-10-03             # 必填，决定排序
summary: 一两句话的摘要       # 卡片和搜索会用到
tags: [Next.js, 日志]         # 可选
updated: 2026-10-05          # 可选，更新日期
code: LOG-100                # 可选，不写会自动编号
draft: true                  # 可选，布尔值，生产网站隐藏草稿
---

新文章填写实际写作日期。更新旧文章时保留 date 并修改 updated；路径决定网址，已发布文章尽量原位更新。draft: true 只影响网站展示，推送后正文仍在仓库与历史里。

#标题与段落

二级标题 ## 会自动编号（§01、§02…）并进入右侧目录；三级标题 ### 也会进入目录。

正文里可以用 加粗、斜体、删除线、行内代码 和链接。外部链接会自动在新标签页打开。

#列表

• 无序列表用 -
• 方块符号是强调色
  • 可以缩进嵌套

1. 有序列表
2. 序号是等宽字体
3. 第三项

• 任务列表也可以
• 未完成的项

#表格

#代码

用三个反引号加语言名，构建时自动高亮，右上角有复制按钮：

export function getDoc(slug: string[]) {
  const key = slug.join("/");
  return load().docs.find((d) => d.slug.join("/") === key) ?? null;
}

#提示框

写法：

<Callout type="warn" title="注意">内容</Callout>

#图片

内容仓库目前不托管图片。新图片优先引用已经存在、允许公开且可访问的 HTTPS URL，并填写替代文字；不要把电脑上的绝对路径写进正文。

网站已有的 /avatar/placeholder.svg 等静态资源可以直接引用。要增加 /archive/2026/demo.png，需要把文件放进 网站代码仓库 的 public/archive/2026/demo.png 并部署网站；只向内容仓库添加 public/ 或 assets/ 不会使图片上线。需要编号和图注时用：

<Figure src="/avatar/placeholder.svg" no="01" caption="图注写在这里" />

#引用与分隔线

引用块适合放摘录或别人说的话。

快捷键用 Ctrl + K 这样写。脚注也支持¹。

#保存与发布

本地保存后，先检查文章字段、正文渲染、链接和图片；准备公开时将 draft 设为 false，按已授权的范围提交并推送到内容仓库的 main。截至 2026-10-05，推送后已有网站内容缓存刷新机制，本地每日自动上传尚未启用。

推送成功后打开文章网址，核对标题、正文和归档入口。只看到 Git 提交成功，还不能确认线上读者已经看到了新版。