写第一篇文章

在工作台“博客”中选择目标目录，再使用“新建”创建文章。也可以在工作区执行：

bookx new post "你好，BookX"
bookx new post "第二篇文章" "随笔/2026"

脚手架默认创建草稿，且不会覆盖已有文件。准备发布时关闭草稿状态，保存后重新构建。

一篇完整的 Markdown

文章可以是 content/blog/ 下的 Markdown 文件，也可以使用独立目录中的 README.md。下面示例中的 ID 必须换成站点内唯一值：

---
id: my-first-bookx-post
title: 你好，BookX
slug: hello-bookx
summary: 记录第一次搭建静态博客的过程。
created_at: 2026-09-11T09:00:00+08:00
updated_at: "2026-09-11T13:25:58+08:00"
category: 随笔
keywords: [Markdown 写作, 静态博客]
tags: [开始, BookX]
draft: true
private: false
toc: true
---

这是文章的开头。

## 为什么开始写作

把遇到的问题和解决过程留给未来的自己。

## 下一步

补充示例，检查链接，然后发布。

模板会使用 Front Matter 的 title 生成页面一级标题，正文通常从二级标题开始。

元信息如何使用

缺失时间时，静态构建优先读取 Git 历史，没有历史再使用文件修改时间。要让本地和 CI 的日期稳定，建议显式填写时间。当前内容模型不使用 published_at。

博客默认按创建时间排序；设置 order 后会参与全站自定义顺序，并影响列表和前后文章导航。显式 order 在所有博客文章中不能重复。归档仍按创建时间倒序排列。

图片、附件和链接

工作台的图片选择器可以上传或选择图库图片，插入的是稳定的媒体引用：

![界面说明](media:a81c9e421923abef){width=60%}

这里的哈希仅展示格式，实际使用图片选择器生成的引用。百分比宽度允许 1% 到 100%，像素宽度允许 1px 到 4096px，图片仍不会超过正文宽度。

同一文章目录也可以保存图片或下载附件，并用相对路径引用。链接其他文档时使用相对 Markdown 路径，构建器会转换为含部署子路径的最终 URL。例如本页可以链接到站点配置。文件移动后需要检查原有相对链接。

内置主题支持点击详情页封面和正文图片预览、查看原图及 Esc 关闭；代码块带复制按钮。正文支持列表、表格、任务列表、删除线、脚注和带语言名称的代码块。可直接粘贴常见 HTML 标签，预览和构建会移除脚本、事件属性、内联样式及危险链接。视频平台的分享 iframe 可直接粘贴到正文（不要放进代码块），例如：

<iframe src="//player.bilibili.com/player.html?isOutside=true&bvid=BV1ge4y117cM" allowfullscreen="true"></iframe>

支持的播放器地址包括 Bilibili player.bilibili.com/player.html、YouTube www.youtube.com/embed/… 和 www.youtube-nocookie.com/embed/…、Vimeo player.vimeo.com/video/…、优酷 player.youku.com/embed/…、腾讯视频 v.qq.com/txp/iframe/player.html?vid=…、西瓜视频 www.ixigua.com/iframe/…。播放器按正文宽度显示；不在列表中的 iframe 会被移除。部分视频可能因平台的站外播放限制而无法加载。正文颜色由主题统一控制；自行设置 CSP 的部署平台还需在 frame-src 中允许相应播放器来源。

发布前检查

1. 确认保存成功，关闭准备公开文章的草稿状态。
2. 检查文章及上级目录的可见性，避免误把私有内容改为公开。
3. 执行 bookx validate 和 bookx build。
4. 打开正式预览检查标题、目录、图片、分类标签和前后文章链接。

仅在“本地预览”看到文章，并不代表它会进入正式发布。两种预览的区别见本地写作工作台。