Markdown 写作工作流整理

好的写作工作流应该减少摩擦。以下内容记录了从文章构思到最终发布的流程优化，适用于任何基于静态站点的内容项目。

内容模板体系

使用脚本创建基础文件可以避免手动设置 frontmatter。内置命令如下：

1
# 博客文章（普通 Markdown）
2
bun run post:new my-article-title
3

4
# MDX 文章（支持组件）
5
bun run post:new my-interactive-post --mdx
6

7
# Vibe 短记录
8
bun run vibe:new today-cloud

这些命令参数是文件 slug，不是最终标题。博客文件会生成到 src/content/blog/，Vibe 文件会按现有约定生成到 src/content/vibe/ 并带日期前缀。

Frontmatter 结构

每篇文章的元数据统一使用 YAML frontmatter：

1
title: '文章标题'
2
description: '用于归档页和元信息的简短摘要。'
3
date: '2026-05-18'
4
draft: false
5
heroImage: '/src/assets/figure/example.png'
6
showHeroImage: true
7
tags:
8
  - Astro
9
comments: true
10
sidebar:
11
  enable: true
12
  toc: true
13
  relatedPosts: true

draft: true 的文章在构建时会被排除，但可以在本地开发环境中预览。

MDX 组件集成

当文章需要交互元素时，使用 .mdx 扩展名并导入项目组件：

1
---
2
title: '带交互内容的文章'
3
---
4

5
import Carousel from '../components/mdx/Carousel.astro';
6

7
这是一篇普通文字段落。下面是嵌入的轮播组件：
8

9
<Carousel images={["/images/photo1.jpg", "/images/photo2.jpg"]} />

常用 MDX 组件包括 LongImage、ZoomableImage、FriendLinkCard 和 Carousel，都在 src/components/mdx/ 目录下。

草稿管理与发布流程

1
# 1. 创建草稿文章
2
bun run post:new draft-title --mdx
3

4
# 2. 本地预览（包含草稿）
5
bun run dev
6

7
# 3. 修改 frontmatter，设置 draft: false
8

9
# 4. 构建并发布
10
bun run build
11
git push origin main

部署自动化

CI/CD 流程应该覆盖以下阶段：

依赖安装 - bun install
生产构建 - bun run build
搜索索引 - Pagefind 自动运行
内容验证 - 检查是否有未完成的草稿
静态部署 - 将 dist 推送到托管平台

GitHub Pages 项目页可使用仓库内置 workflow。astro.config.mjs 会根据 GitHub Actions 环境自动处理项目页 base，也可以手动覆盖：

1
SITE_URL=https://example.com SITE_BASE=/my-site bun run build

写作习惯建议

每天固定时间写 30 分钟比偶尔集中写作更有效
使用 draft 功能减少发布压力
为长文章设置里程碑节点
Vibe 记录适合碎片想法，博客适合深度展开