写作与发布指南

这个博客把 content/ 目录当作一个 Obsidian 仓库（vault）。你可以直接用 Obsidian 打开它，写完保存，博客就会更新。

快速开始#

npm install      # 安装依赖
npm run dev      # 本地预览：http://localhost:4321
npm run new -- "文章标题" 技术   # 用模板新建一篇文章（可选分类）
npm run build    # 构建静态站点到 dist/

Frontmatter 字段#

所有字段都是可选的：

---
title: 文章标题          # 默认取正文第一个一级标题，再退回到文件名
date: 2026-10-01         # 发布日期（也认 created）；默认取文件创建时间
updated: 2026-10-05      # 更新日期（也认 modified）
category: 技术/前端      # 分类（可多级）；默认取所在的文件夹层级
tags: [前端, react]      # 标签；正文里的 #标签 也会被收录
description: 一句话摘要  # 显示为文章副标题，也用于列表和 SEO；不写则自动截取正文
cover: "[[封面.png]]"    # 封面图，支持 [[双链]]、相对路径或网址
slug: my-post            # 自定义网址；默认用文件名
aliases: [别名]          # 别名，可用于 [[别名]] 链接
pinned: true             # 首页置顶
categoryPinned: true     # 在所属分类中置顶；也可写上级分类名，如 Web 安全，或多个 [JWT, Web 安全]
draft: true              # 草稿：本地预览可见，构建时不发布（也认 publish: false）
cssclasses: [wide]       # 自定义 CSS 类（wide 让正文更宽）
---

分类与标签#

• 分类：默认就是文章所在的文件夹层级，支持任意多级子分类。例如 content/技术/前端/xxx.md 属于「技术 › 前端」，父分类「技术」会同时包含所有子分类的文章。也可以在 frontmatter 里用 category: 技术/前端 或 categories: [技术, 前端] 指定；site.config.ts 中的 categoryDepth 可以限制最多取几层文件夹。
• 标签：frontmatter 里的 tags 与正文中的 #标签 都会被收录，支持 #父/子 这样的嵌套标签。
• 以 . 或 _ 开头的目录（比如 .obsidian、_templates）不会被发布，但里面的图片仍然可以被引用。

图片与附件#

把图片放在仓库任意位置（推荐 attachments/），用 ![[图片.png]] 引用即可，规则与 Obsidian 一致：只写文件名就能找到。也支持：

• ![[图片.png|300]]、![[图片.png|300x200]] 指定尺寸
• ![[音频.mp3]]、![[视频.mp4]]、![[文档.pdf#page=3]]

部署#

npm run build 会生成纯静态文件，可以部署到任何静态托管：

1. GitHub Pages：项目已包含 .github/workflows/deploy.yml，推送到 main 分支即自动发布。在仓库设置 → Pages 中把 Source 设为「GitHub Actions」。
2. Vercel / Netlify / Cloudflare Pages：构建命令 npm run build，输出目录 dist。

更多语法示例见 Obsidian 语法全览。