MORRO
b8b2f5fe14
Refine TOC and cover styling, add numbered headings and gray body text, unify #f6f7f8 surfaces, and replace sample content with a Markdown usage manual. Co-authored-by: Cursor <cursoragent@cursor.com>
198 lines
6.4 KiB
Markdown
198 lines
6.4 KiB
Markdown
---
|
||
title: "GreLin 技术报告\n模板使用说明"
|
||
company: 西安高岭绿能科技有限公司
|
||
date: 2026-06-22
|
||
version: v2.0
|
||
summary: |
|
||
本手册面向首次使用 GreLin 技术报告模板的同事，说明如何编辑 Markdown 正文、配置封面元数据、预览排版效果并导出 PDF。按章节操作即可完成一份符合 GreLin 版式规范的技术报告。
|
||
---
|
||
|
||
# 快速开始
|
||
|
||
技术报告的主编辑入口是 `tech-report/content/report.md`。你**几乎不需要修改 Typst 代码**，只需在该 Markdown 文件中撰写正文，并维护文件开头的 YAML 元数据。
|
||
|
||
推荐工作流如下：
|
||
|
||
1. 用 VS Code 或 Cursor 打开仓库，编辑 `content/report.md`。
|
||
2. 打开 `report.typ`，使用 Tinymist 扩展的 **Typst Preview** 实时预览。
|
||
3. 确认无误后，执行 **Typst Export PDF** 或使用命令行导出。
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
typst compile --root . tech-report/report.typ tech-report/sample.pdf
|
||
```
|
||
|
||
> 提示：封面、目录、页码与正文样式已由模板封装；日常写作只需关注 `report.md` 与 `content/assets/` 中的图片资源。
|
||
|
||
# 报告元数据
|
||
|
||
元数据写在 `report.md` 最上方的 YAML 区块（两行 `---` 之间）。编译时会自动填充封面与文档属性。
|
||
|
||
常用字段如下：
|
||
|
||
| 字段 | 说明 | 示例 |
|
||
| ---- | ---- | ---- |
|
||
| `title` | 报告标题（封面与页眉） | `某某项目技术报告` |
|
||
| `company` | 编制单位 | `西安高岭绿能科技有限公司` |
|
||
| `date` | 日期，格式 `YYYY-MM-DD` | `2026-06-22` |
|
||
| `version` | 版本号 | `v1.0` |
|
||
| `summary` | 摘要正文（不含「摘要」标题，目录中也不列出） | 多行文本 |
|
||
|
||
示例：
|
||
|
||
```yaml
|
||
---
|
||
title: 智能矿石分选系统技术报告
|
||
company: 西安高岭绿能科技有限公司
|
||
date: 2026-06-22
|
||
version: v1.0
|
||
summary: |
|
||
此处填写摘要段落……
|
||
---
|
||
```
|
||
|
||
若某字段缺省，可在 `data/config.typ` 中查看并修改默认值。
|
||
|
||
## 封面标题换行
|
||
|
||
封面主标题支持**手动指定换行**，避免长标题挤在一行显得杂乱。在 YAML 中用多行写法即可：
|
||
|
||
```yaml
|
||
title: |
|
||
GreLin 技术报告模板
|
||
使用说明
|
||
```
|
||
|
||
第一行显示为较小字号，第二行显示为更大字号（与「智能矿石分选」类报告一致）。也可在单行标题里写 `\n`：
|
||
|
||
```yaml
|
||
title: "智能矿石分选\n技术报告"
|
||
```
|
||
|
||
若未手动换行，标题中含「智能」时会自动在「智能」后断开（兼容旧写法）。
|
||
|
||
# 撰写正文
|
||
|
||
## 标题层级
|
||
|
||
正文使用 Markdown 标题组织章节，模板会自动编号并套用 GreLin 样式：
|
||
|
||
- `# 一级标题` → 显示为 **1**、**2**……，整行蓝色
|
||
- `## 二级标题` → **1.1**、**1.2**……，编号蓝色、标题黑色
|
||
- `### 三级标题` → **1.1.1** 形式
|
||
- `#### 四级标题` → **1.1.1.1** 形式
|
||
|
||
标题与后续正文之间会自动换行，无需手动插入空行。
|
||
|
||
## 摘要与目录
|
||
|
||
- **摘要**：写在 YAML 的 `summary` 字段；正文区不再重复「摘要」标题，且与第一章可在同一页连续排版。
|
||
- **目录**：由模板自动生成，仅列出正文章节；摘要与「术语与缩写」不会出现在目录中。
|
||
- **术语与缩写**：在 `data/glossary.typ` 维护，报告末尾自动输出，同样不进目录。
|
||
|
||
# Markdown 语法
|
||
|
||
普通段落默认为灰色正文；需要强调时，可使用下列写法。
|
||
|
||
## 强调与高亮
|
||
|
||
- **加粗**：`**重点内容**`，仅加粗，不改变颜色
|
||
- *斜体*：`*补充说明*`，仅斜体，不改变颜色
|
||
- **高亮**：`<mark>关键指标</mark>`，浅蓝底突出显示
|
||
- <u>下划线</u>：`<u>术语或指标</u>`，蓝色下划线
|
||
- ~~删除线~~：`~~已废弃方案~~`
|
||
- 行内代码：`` `25 t/h` ``，浅灰底、等宽字体
|
||
|
||
示例：单线设计处理量 <mark>25 t/h</mark>，精矿 A/S 可达 **4.0+**。
|
||
|
||
## 链接
|
||
|
||
Markdown 链接会自动渲染为**蓝色并带下划线**：
|
||
|
||
- 带显示文字：`[GreLin 文档](https://typst.app/docs/)`
|
||
- 直接写 URL：`<https://typst.app/docs/>` 或 `https://typst.app/docs/`
|
||
|
||
示例：编译说明见 [Typst 官方文档](https://typst.app/docs/)，也可访问 <https://typst.app/docs/>。
|
||
|
||
## 列表、引用与表格
|
||
|
||
无序列表：
|
||
|
||
- 条目一
|
||
- 条目二
|
||
|
||
有序列表：
|
||
|
||
1. 第一步：准备素材与数据
|
||
2. 第二步：撰写各章节
|
||
3. 第三步：预览并导出 PDF
|
||
|
||
引用块：
|
||
|
||
> 政策与市场需求推动预选抛废技术应用。引用块适合摘录标准、政策原文或补充说明。
|
||
|
||
表格示例：
|
||
|
||
| 指标 | 设计值 | 备注 |
|
||
| ---- | ------ | ---- |
|
||
| 单线处理量 | 25 t/h | 可调整 |
|
||
| 精矿 A/S | ≥ 4.0 | 实验室验证 |
|
||
|
||
## 图片与代码
|
||
|
||
图片放在 `content/assets/`，在 Markdown 中相对引用：
|
||
|
||
|
||
|
||
代码块支持语法高亮（由 codly 渲染）：
|
||
|
||
```python
|
||
# 示例：处理产线数据流
|
||
for sample in belt_stream:
|
||
grade = model.infer(sample)
|
||
valve.fire(grade)
|
||
```
|
||
|
||
# 高级功能
|
||
|
||
## 术语与缩写
|
||
|
||
在正文中引用术语表条目，使用 raw-typst 嵌入：
|
||
|
||
- 首次出现：<!--raw-typst #gls-long("hsi") -->
|
||
- 再次出现：<!--raw-typst #gls-short("onnx") -->
|
||
|
||
术语定义集中在 `data/glossary.typ`，报告末尾会自动生成「术语与缩写」一节。
|
||
|
||
## 插入 Typst 组件
|
||
|
||
复杂图表或自定义组件可在 Markdown 中插入 Typst 代码：
|
||
|
||
<!--raw-typst #ore-sorting-flow()-->
|
||
|
||
如需新增组件，在 `data/` 下编写 Typst 函数，并在 `report.typ` 的 `extra-scope` 中注册后，即可用 `<!--raw-typst #函数名()-->` 调用。
|
||
|
||
# 版式说明
|
||
|
||
| 页面 | 边距 | 说明 |
|
||
| ---- | ---- | ---- |
|
||
| 封面 | 自定义 | 左侧蓝色色块贴边，见 `data/cover.typ` |
|
||
| 目录 | 2.5 cm | 较宽边距，便于大号章节编号排版 |
|
||
| 正文 | 2 cm | 摘要及正文内容使用较窄边距 |
|
||
|
||
正文无页眉；页码从正文第一章起算，格式为 `当前页 / 总页数`，位于页脚右侧。
|
||
|
||
# 常见问题
|
||
|
||
**Q：修改 Markdown 后预览没有更新？**
|
||
A：保存 `report.md` 后，Typst Preview 通常会自动刷新；若无反应，可关闭预览后重新打开 `report.typ`。
|
||
|
||
**Q：图片找不到？**
|
||
A：确认路径相对于 `content/report.md`，且文件位于 `content/assets/` 目录下。
|
||
|
||
**Q：想改主题色或字号？**
|
||
A：编辑 `data/theme.typ`；品牌色也可在仓库根目录 `brand/colors.typ` 统一调整。
|
||
|
||
完成以上步骤后，你即可基于本模板快速产出 GreLin 风格的技术报告。祝写作顺利。
|