78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# 脚手架
|
||
|
||
脚手架在 Phase 4 创建文章工作区，**不把工程代码塞进 SKILL.md**。工程模板是 Skill
|
||
assets（`assets/scaffold-template/`），由 `scripts/scaffold.sh` 复制并接线。
|
||
|
||
## 用法
|
||
|
||
```bash
|
||
bash <path-to-beautiful-article>/scripts/scaffold.sh ./my-article --theme=tufte
|
||
bash <path-to-beautiful-article>/scripts/scaffold.sh ./brief --theme=press --no-cover
|
||
bash <path-to-beautiful-article>/scripts/scaffold.sh --list-themes
|
||
```
|
||
|
||
`--theme` 必须是 `theme-profiles/index.json` 里的 id（当前 `tufte` / `press` / …）。工作区可建在
|
||
**任意目录**，不需要在 reacticle 仓库内。
|
||
|
||
`--no-cover` 禁用书封式文章封面（默认开 · 屏幕 3:4 / PDF 独占首页）。Checkpoint 1 用户
|
||
选了"封面 · 关"时传这个。详见 `references/cover.md`。
|
||
|
||
## 脚手架做什么
|
||
|
||
- 创建工作区目录 + 复制 Vite / React / TS 模板。
|
||
- **从 npm 安装最新发布版的 `reacticle`**：`package.json` 里 `reacticle: "latest"`，脚手架
|
||
装完依赖后再 `npm install reacticle@latest` 强制刷新到当下最新，并打印实际版本。
|
||
- 在 `article/main.tsx` 写入所选 runtime theme id，并 `import "reacticle/styles.css"`。
|
||
- 创建默认 `article/Article.tsx` + `article/sections/`、`article/raw-blocks/`、
|
||
`article/assets/`。`Article.tsx` 末尾自带 **colophon Raw 块**（`Made with
|
||
[beautiful-article](github 仓库) · <主题> theme`），样式低对比小字、走 `--ra-*` token，
|
||
**不可删除**（见 SKILL.md「默认策略」）。
|
||
- 默认创建 **`article/Cover.tsx`**（书封式封面外壳 + 占位：屏幕 3:4 / PDF 独占首页）并在
|
||
`main.tsx` 里渲染 `<Cover />` 在 `<ArticleDoc />` 之上。`--no-cover` 时跳过这一步：
|
||
不复制 Cover.tsx，并从 `main.tsx` 剥掉 `__COVER_IMPORT_*__` / `__COVER_RENDER_*__`
|
||
标记包裹的两段。封面设计见 `references/cover.md`。
|
||
- 创建工作记忆目录 `source/`、`plan/`、`review/`。
|
||
- `katex` / `prismjs` 作为 `reacticle` 的依赖会被自动带下来，无需在工作区单独声明。
|
||
|
||
## 升级组件库
|
||
|
||
工作区随时可升级到最新组件库：
|
||
|
||
```bash
|
||
npm install reacticle@latest
|
||
```
|
||
|
||
## 工作区结构
|
||
|
||
```text
|
||
my-article/
|
||
package.json vite.config.ts tsconfig.json tsconfig.node.json index.html
|
||
source/ plan/ review/
|
||
article/
|
||
main.tsx # 入口：<ThemeProvider theme="..."> + <Cover/> + <ArticleDoc/>
|
||
Cover.tsx # 书封式文章封面：屏幕 3:4 / PDF 独占首页（默认；--no-cover 时不生成）
|
||
Article.tsx # assembler（主 Agent 拥有）：import + 排序各 Section，不写 Section 正文
|
||
sections/ # 一节一文件（铁律）：NN-*.tsx，每个导出一个 Section 组件
|
||
01-opening.tsx
|
||
raw-blocks/ # 大型 Raw 隔离：NN-*.tsx
|
||
assets/ # 配图素材
|
||
.theme # 记录起步主题
|
||
```
|
||
|
||
> **一个 Section = 一个文件**（`sections/NN-*.tsx`），坚决不允许把多个 Section 写进
|
||
> `Article.tsx`。`Article.tsx` 只做组装。这是多 Agent 并行（开发模式由 Checkpoint 2 选定）
|
||
> 的前提，详见 `references/section-build.md`。
|
||
|
||
## 切主题
|
||
|
||
改两处（脚手架默认会把主题名注入到这两个位置）：
|
||
|
||
1. `article/main.tsx` 里 `<ThemeProvider theme="...">`（控制运行时主题）。
|
||
2. `article/Article.tsx` 末尾的 colophon `· <主题> theme`（控制印记里显示的主题名）。
|
||
|
||
两处保持一致。详见 `html-output.md`。
|
||
|
||
## 构建 / 预览
|
||
|
||
见 `references/html-output.md`（`npm run dev` / `build` / `html`）。
|