高木

1. 文章放在哪里#

• 内容分离模式（推荐）下：在 content/posts/ 新建文章。
• 该目录会同步映射到 src/content/posts/，由 Astro 内容集合读取。
• posts 下不要放无 Frontmatter 的说明型 .md（如 README.md），否则会被当文章解析并报错。

2. 文件组织规范#

• 简单文章：content/posts/my-post.md
• 含本地图片文章：content/posts/my-post/index.md + 同目录图片文件
• 当前集合仅扫描 *.md，不建议使用 .mdx。

3. Frontmatter 标准#

最小必填：

1
---
2
title: 文章标题
3
published: 2026-04-07
4
---

推荐模板：

1
---
2
title: 文章标题
3
published: 2026-04-07
4
updated: 2026-04-07
5
description: 文章摘要
6
image: ./cover.png
7
tags: [Astro, 教程]
8
category: 前端
9
draft: false
10
pinned: false
11
comment: true
12
lang: zh_CN
13
author: YourName
14
sourceLink: ""
15
licenseName: ""
16
licenseUrl: ""
17
encrypted: false
18
password: ""
19
passwordHint: ""
20
alias: ""
21
permalink: ""
22
---

4. 图片与封面规则#

• image 支持三种写法：
• https://...：外链图
• /images/...：公共静态图（来自 public/images）
• ./cover.png：相对当前 Markdown 文件目录

建议：有封面或配图的文章使用“目录 + index.md”结构，图片与正文同目录，迁移最稳。

5. 标签与分类命名建议#

• 站点语言为中文时，category 建议中文（如“写作指南”“前端”）。
• tags 可中英混用，但建议“一个体系内保持一致”：
• 通用主题用中文（如“教程”“性能优化”）
• 技术专有词保留英文（如 Astro、TypeScript）

6. 密码保护（开关方式）#

开启加密：

1
encrypted: true
2
password: "你的密码"
3
passwordHint: "可选提示"

关闭加密：

1
encrypted: false
2
password: ""
3
passwordHint: ""

注意：仅 encrypted: true 且 password 非空时才会实际启用密码保护。

7. 草稿与上线逻辑#

• draft: true：开发环境可见，生产构建会隐藏。
• draft: false：正常参与首页、归档、RSS（加密文另有过滤逻辑）。

8. 链接规则（Slug / Alias / Permalink）#

• 默认链接：/posts/<文件名或目录名>/
• alias：生成 /posts/<alias>/
• permalink：使用站点根路径自定义链接（优先级更高）

除非你明确要做旧链接兼容或 SEO 固定路径，否则建议先用默认链接。

9. 新建与发布流程#

1. 新建文章：pnpm new-post <slug>
2. 编辑 content/posts/... 文档与图片
3. 本地检查：pnpm dev
4. 发布前检查：pnpm lint && pnpm check && pnpm build

10. 常见错误清单#

• 缺少 title 或 published
• 在 posts 放了非文章型 .md
• image 相对路径写错（目录层级不匹配）
• 只写 encrypted: true 但忘了 password
• 发布后文章不见：通常是 draft: true

11. 布尔字段分层（避免混淆）#

这几个字段都写 true/false，但控制层级不同，容易混：

附录：Frontmatter 字段作用总表（除 title）#

下表按项目实际 schema（src/content.config.ts）整理，聚焦“这个字段控制什么”。

实务建议：日常写作优先维护 published、description、image、tags、category、draft、pinned、encrypted/password、alias/permalink 这组核心字段。