文件格式

.hy.md：一份纯文本，四种看法

.hy.md = 文首 YAML + 标准 Markdown 正文 + 可拔插围栏块。任何 Markdown 工具都能打开，扩展块自动降级为代码块；Cursor、Claude Code 等 Agent 可以直接读写。本页的示例都取自 HyMd 自己的开发文档。

核心概念：一源四视图 + 旁车

HyMd 的格式只有一条底线：源文件是唯一的正文。排版、幻灯、论文都不是另存的副本，而是同一份源的“投影”；每个视图自己的调整（隐藏某段、从此分页、演讲者备注、跨两栏……）写在源旁边的视图胶片里，不写进源。

源 · 唯一真相

报告.hy.md标准 Markdown + 文首 YAML + 围栏块

文首 YAML标准层正文围栏块

人和 Agent 都只改这一份

直接编辑

正文所见即所得写作

views/paper.hy.md

排版A4 纸面 · 分页 · 毫米尺

views/deck.hy.md

幻灯按标题切页 · 备注

views/article.hy.md

论文中文期刊 / IEEE 双栏

视图 = 源 + 自己的胶片（纯函数投影）。在幻灯里隐藏一段、在论文里让图跨两栏，只写进对应胶片；三个视图互不可见，源一字不改。

降级优先

在 Typora、VS Code、GitHub 里都必须可读。扩展块降级为代码块，胶片在普通编辑器里也照样可读可改。

Agent 友好

全是纯文本：YAML、Markdown、围栏。Agent 不需要任何插件就能读写，Git 能逐行 Diff。

不复制正文

同一篇说明直接出纸面、出幻灯、出期刊样，不用像 Marp 那样另写一份稿。

同一份源，四种投影（真实界面，点击放大）

正文视图：滚到标题「设计说明」。
纸面排版：同一份源按纸张、页边距和分栏排成页面，带毫米尺。
幻灯视图：按标题拆成幻灯页，工具条可换主题并导出 pptx / pdf。
论文视图：按期刊版式重排题头与正文。

三层结构

层	内容	在普通 Markdown 工具里
文首 YAML	标题、主题、`page:` 纸张几何、`deck:` 幻灯设置、`references:` 参考文献、`hy:` 引用锚点（规划中）	YAML 块 / GitHub 表格
标准层	CommonMark / GFM：段落、H1–H6、分隔线、三种列表、引用、代码块、管道表、图片、行内 / 块级公式、五类 GFM 提示框	原样显示
围栏块层	`sheet` `slide` `mermaid` `layout` `calc` `figure`、条形图、HTML / SVG、`latex` 等公式围栏	代码块

普通 .md / .txt 也能在 HyMd 里打开：标准层照常编辑，只是围栏块没有卡片交互，当作代码块显示。

文首 YAML

纸张几何 `page:`

下面是开发文档里一份真实的文首：横向 A2、594×420 mm、4 栏、栏间距 8 mm，边距按上、右、下、左排列。排版视图的几何自 2026-09-29 起写进胶片；编辑器纸面布局的几何仍写在源文首。

Research/05-排版预览后所见即所得.md · 第 1–17 行真实文件

---
page:
  preset: A2
  series: A
  elongation: 1
  orientation: landscape
  columns: 4
  gutter_mm: 8
  margin_mm:
    - 10
    - 10
    - 10
    - 25
  width_mm: 594
  height_mm: 420
---

幻灯 `deck:` 与论文 `references:`

幻灯视图读文首 deck:（主题 / 尺寸 / 切页级别）；胶片里的 theme / size / split 优先。
论文视图读文首 references:；正文 [@key] 按首次出现编号成 [n]。
设置取值级联：胶片 settings → 源文首旧字段（page: / deck:）→ 视图默认值。

正文里的视图注释

少量视图控制用 HTML 注释写在正文里——普通渲染器完全看不见它们。

注释	作用
`<!-- page: break -->`	排版：下一块从新页开始
`<!-- page: span -->`	论文：该块跨两栏（IEEE 题头默认加）
`<!-- deck: break -->`	幻灯：强制切页
`<!-- hymd:b N -->`	预览内部块标记，导出时去掉

幻灯切页只认标题级别和 ；正文里独占一行的 --- / *** / ___ 会换成分隔线，避免多出空白页。

围栏块

每种扩展都只是一个带语言名的围栏代码块。在 HyMd 里它们是可交互卡片；离开 HyMd，它们就是一段可读的代码。

`sheet` 电子表格

围栏正文是 YAML（id / rows / cols / snapshot），表格数据快照存在 {文档名}.assets/{blockId}.univer.json。编辑器里显示为 HTML 表卡片，点击开 Univer 编辑叠层；可降级为 GFM 管道表，也可从 GFM 表升级。HyMd 的开发文档里就有 12 个这样的真实快照。

`mermaid`

流程图 / 结构图，卡片显示 SVG，右侧改源码。HyMd 开发文档大量使用。

`slide`

文内嵌一段 Marp 幻灯，卡片显示缩略图；.marp.md 文件另有源码编辑标签。

`latex` 等公式

KaTeX 预览；可复制成 Word 可编辑公式或 Excel 图完善中

`layout`

页宽、锚点等排版设定。

`calc`

公式与输入写在文里，当前不求值完善中

条形图

对象字面量描述数据，画静态 SVG，不执行代码 完善中

`html` / `svg`

就地画成可关闭的小页面，关掉不写回完善中

在正文里插入围栏块（真实界面，点击放大）

在空段键入 /，弹出插入目录：表格、图版、块级公式等。
插入表格扩展块，正文里出现可编辑的表格卡片。
插入图版扩展块，卡片按两列空位铺开。
插入块级公式，正文直接排出公式，而不是留下源代码。

插入的每个块，在源文件里都只是一段带语言名的围栏代码。

`figure` 图版块完善中

把大小不一的 AI 出图、截图、现场照片排成统一的毫米格子，导出前自动检查像素够不够印。原则是“适配不落盘，声明落盘”：编辑与预览时用 CSS object-fit 现场画，只有导出才栅格化，原图永远不被改。

文档.hy.md围栏约定

```figure id=fig-xxxx
cols: 2
aspect: 4:3
gap_mm: 4
fit: cover
min_dpi: 300
cells:
  - src: ./doc.assets/images/a.png
    caption: 左视图
  - src: ./doc.assets/images/b.png
    fit: contain
```

字段	含义	默认
`cols`	每行几格	2
`aspect`	格子宽:高（`4:3` / `16:9` / `1:1`）	`4:3`
`gap_mm`	格间距（mm）	4
`fit`	`cover` 铺满切边 / `contain` 完整留白；格内可覆盖	`cover`
`view_mm`	观看距离（mm）；未写 `min_dpi` 时按人眼 1 弧分极限算 DPI	300（≈291 DPI）
`min_dpi`	最低印刷 DPI，显式写出时盖过 `view_mm`	由观看距离算出
`cells[].src`	相对文档的图路径	空格子
`cells[].caption`	格下小字	无
`cells[].anchor`	切割锚点 center / top / bottom / left / right	`center`
`cells[].upscale`	auto / none / nearest / bilinear / bicubic / lanczos3	`auto`

格宽怎么算：格宽 mm = (正文宽 mm − gap × (cols − 1)) ÷ cols。正文宽默认 170 mm（A4 竖版、左右各 20 mm）。例如默认 2 栏、4 mm 间距，每格 83 mm 宽。

区域版式：图 + 后随段落

加上 template= 后，围栏后面直到空行或下一个标题 / 围栏之前的段落会被绑定为文字区，实现左图右文等版式。

文档.hy.md示意，非定稿

```figure id=fig-1 template=img-left
cols: 1
fit: contain
cells:
  - src: ./a.png
    caption: 左视图
```

左侧为变形前，右侧为加载后。

内联样式落盘

工具条上的样式都落成普通工具也能读的 HTML，不发明私有语法：

下划线 → <u>
字色 / 背景 → <span style data-hymd-*>
非左对齐的段落 / 标题 → <p style="text-align"> / <hN style="text-align">
批注色点 → GFM Alert：> [!NOTE] 等

引用与原文锚点规划中

文献屉已经可以插入 [@键] 并导入 / 导出 RIS、BibTeX、CSL-JSON。下面是已定稿、尚在实现中的句子级引用方案：参考文献用 CSL YAML，HyMd 自己的扩展放在条目的 hy: 子键里（verify、zotero、aliases、source），Pandoc 会忽略它们，实测零告警。

RGC 讲义.hy.md定稿方案 · 规划中

---
title: RGC 讲义（示例）
references:
  - id: williams2017vitamin
    type: article-journal
    title: "Vitamin B3 modulates mitochondrial vulnerability and prevents glaucoma in aged mice"
    author: [{family: Williams, given: PA}, {family: Harder, given: JM}]
    container-title: Science
    issued: {date-parts: [[2017]]}
    DOI: 10.1126/science.aal0092
    PMID: "28209901"
    hy:
      verify: {status: verified, checkedAt: 2026-10-11, sources: [crossref, pubmed]}
  - id: tian2022core
    type: article-journal
    title: "Core Transcription Programs Controlling Injury-Induced Neurodegeneration of Retinal Ganglion Cells"
    DOI: 10.1016/j.neuron.2022.06.003
    hy:
      verify:
        status: concern
        checkedAt: 2026-10-11
        sources: [crossref]
        updates:
          - {type: expression_of_concern, DOI: 10.1016/j.neuron.2024.06.010, date: 2024-07-17}
hy:
  version: 1
  anchors:
    - id: a1
      cite: williams2017vitamin
      target: {exact: "小鼠膳食烟酰胺在最高剂量使 93% 眼不发生青光眼"}
      body:
        exact: "At the highest dose tested, 93% of eyes did not develop glaucoma."
        origin: pubmed-abstract
        basis: abstract
        stance: support
        confirmedAt: 2026-10-11
---

小鼠膳食烟酰胺在最高剂量使 **93% 眼不发生青光眼** [@williams2017vitamin]；核心损伤转录程序为 ATF3、ATF4、C/EBPγ、CHOP [@tian2022core]。

正文只写标准 Pandoc 引用

正文写法

正文只写标准 Pandoc 引用，后面不挂任何附加标记：

[@a, p. 33]
[见 @a; @b, pp. 3-5, 表 2]
[-@a]
@a [p. 33]

锚点两头都是原文

target：本稿里的那句话（规范化后）。
body：来源原文，可带 page、pdf 坐标、origin、basis、stance（support / partial / contrast）、zoteroAnnotation。
两头都采用 W3C TextQuoteSelector。
锚点也可放进旁车 {stem}.assets/citations.json，.hy.md 的一切都能无损映射回纯 .md。

“GitHub 干净版”隐藏行

需要把锚点留在正文里又不想打扰阅读时，每条锚点写成一行链接定义——在 Pandoc、markdown-it、commonmark.js、GitHub API 里都不显示（实测）：

唯一规范写法

[hy:<id>]: <hy:anchor> "<base64url(UTF-8 紧凑 JSON)，不带 = 填充>"

旁车文件与视图胶片

所有附属文件都放在与源同名的 .assets 文件夹里；名称以 .assets 结尾的文件夹在 HyMd 资源管理器里默认不列出，文件树保持干净。源文件改名或移动时，胶片夹会跟着搬。

目录约定

报告.hy.md                         ← 源（唯一真相）
报告.assets/
  images/…                         ← 插图（默认插入位置）
  <blockId>.univer.json            ← sheet 快照
  <figureId>/export/…              ← 图版导出栅格（导出时生成）
  views/paper.hy.md                ← 排版视图胶片
  views/deck.hy.md                 ← 幻灯视图胶片
  views/article.hy.md              ← 论文视图胶片
  views/article.ieee.hy.md         ← 论文视图命名变体
  citations.json                   ← 引用锚点旁车（规划）
报告.exports/报告.deck.pptx         ← 幻灯导出

一份真实的 `paper.hy.md`

这是 HyMd 开发文档 02-项目架构.md 旁边真实存在的排版视图胶片。它说明了胶片的最小形态：声明自己是哪个视图、指向哪份源；settings 为空就表示全部用默认值。

02-项目架构.assets/views/paper.hy.md真实文件

---
hymd_view: paper
version: 1
source: ../../02-项目架构.md
settings: {}
---

胶片里的操作：`hyview` 围栏

每个 hyview 围栏是一条操作，它后面直到下一个 hyview 之前的 Markdown 就是这条操作带的内容。下面这份幻灯胶片在“1 概述”前插入封面、在“2.1 恒载”处强制切页、把一段计算替换成两条要点——原稿一个字都没动。

报告.assets/views/deck.hy.md示意，非定稿格式

---
hymd_view: deck
version: 1
source: ../../报告.hy.md
settings:
  theme: gaia
  size: "16:9"
  split: 2
---

```hyview op=insert where=before
anchor:
  path: "1 概述"
  quote: "本报告复核某桥"
```

# 某桥荷载复核

汇报人 · 2026-09

```hyview op=attr
anchor:
  path: "2 荷载/2.1 恒载"
  hash: 9f2c71ab
  quote: "恒载取 5.0 kN/m²"
attrs:
  break: true
```

```hyview op=replace
anchor:
  id: calc-dead
```

- 恒载 5.0 kN/m²
- 活载 3.5 kN/m²

六种操作

settings · hide · replace · insert · attr · note

锚点线索（按顺序尝试）

显式 id
块指纹
原文摘录
结构路径
模糊摘录规划中
失联 → 进清单等你改挂

五条不变式（已写成单元测试）

视图的保存路径永不等于源路径。
视图只读“源 + 自己的胶片”，三个视图互不可见。
投影是纯函数：同样的输入，永远同样的输出。
源怎么改都不删胶片条目——找不到锚点就进失联清单。
删掉胶片 = 视图回到默认。

降级表现：离开 HyMd 也能读

在 Typora / VS Code / GitHub 里

标准层原样显示；围栏块显示为代码块；文首 YAML 显示为 YAML 块（GitHub 渲染为表格）；视图注释不可见。

胶片在普通编辑器里

视图专属内容（封面、要点）照常可读可改，hyview 只当代码块。

引用

正文是标准 Pandoc 引用；隐藏锚点行在 GitHub / Pandoc / markdown-it 中不显示（实测），Obsidian、Typora 中的表现待验证。

交给 Agent

纯文本、无私有二进制。Agent 改正文，视图标记按结构路径等线索自动找回。

看这些格式能力用在哪里

工程计算书、汇报幻灯、期刊样自检……

使用场景功能详解

.hy.md：一份纯文本，四种看法

核心概念：一源四视图 + 旁车

降级优先

Agent 友好

不复制正文

同一份源，四种投影（真实界面，点击放大）

三层结构

文首 YAML

纸张几何 page:

幻灯 deck: 与论文 references:

正文里的视图注释

围栏块

sheet 电子表格

mermaid

slide

latex 等公式

layout

calc

条形图

html / svg

在正文里插入围栏块（真实界面，点击放大）

figure 图版块 完善中

区域版式：图 + 后随段落

内联样式落盘

引用与原文锚点 规划中

正文只写标准 Pandoc 引用

锚点两头都是原文

“GitHub 干净版”隐藏行

旁车文件与视图胶片

一份真实的 paper.hy.md

胶片里的操作：hyview 围栏

六种操作

锚点线索（按顺序尝试）

五条不变式（已写成单元测试）

降级表现：离开 HyMd 也能读

在 Typora / VS Code / GitHub 里

胶片在普通编辑器里

引用

交给 Agent

看这些格式能力用在哪里

纸张几何 `page:`

幻灯 `deck:` 与论文 `references:`

`sheet` 电子表格

`mermaid`

`slide`

`latex` 等公式

`layout`

`calc`

`html` / `svg`

`figure` 图版块完善中

引用与原文锚点规划中

一份真实的 `paper.hy.md`

胶片里的操作：`hyview` 围栏