Notist
On this page
  1. Vault 组件示例
  2. panel
  3. badge
  4. diagram
  5. 内容状态
  6. 自身配置
  7. Example
  8. 构建与预览
  9. 验证

Vault 组件示例

本目录提供文档 Vault 自用的 panel、badge 与 diagram，由同目录 lib.notc 声明。panel 与 badge 使用本地 Web Component，diagram 通过输出配置选择渲染器。本页以 components 导入该模块，数学模块按需直接导入。可复用模块及其边界见 本地模块。

panel

fn panel(title: String = "Panel", expanded: Bool = true)[children: BlockContent] -> BlockContent;

panel 是块级内容函数。title 显示标题，expanded 决定初始展开状态；正文通过唯一的 children 槽传入，组件使用 slot 显示已渲染的内容。children 保留在文档 IR 中，组件内部的 DOM 不进入 IR。

panel/index.js 默认导出 HTMLElement 类，相对导入 style.js；HTML host 按规范函数身份注册组件，并复制组件目录以保留 import 路径。

badge

fn badge(label: String, count: Int = 1) -> InlineContent;

badge 是行内内容函数，显示 label 与 count。badge.js 是单文件组件入口；使用 BigInt 读取 count，保留 i64 精度。HTML host 按规范函数身份注册组件。

完整参数协议与生命周期契约见 BlockContent Function Extensions。

diagram

fn diagram(source: String, theme: String = "auto") -> BlockContent;

diagram 显示块级图形，source 使用 Mermaid 语法。theme 为 auto、light 或 dark；auto 跟随页面或系统主题。具体渲染器通过配置选择。

docs/Notist.toml 选择具体实现：

[[extensions]]
kind = "replace"
imports = { components = "components/lib.notc", pele = "../modules/pele/lib.notc" }
from = "components.diagram"
to = "pele.diagram"

切换为 Mermaid 时，将该规则的 pele 导入改为 mermaid = "../modules/mermaid/lib.notc"，并将 to 改为 "mermaid.diagram"。两个目标的参数、默认值与返回类型一致；正文只调用 #components.diagram(...)。

上例使用 Pele 渲染；更换渲染器时，正文中的调用保持不变。

内容状态

状态通过 @(status: "...") 注解已有节点，HTML 映射为 data-status。它不建立函数调用边界，普通内容、查询与源码范围保持原有结构。

status

含义

默认样式

draft

方案仍在讨论

绿色虚线框与 Draft · 草案标签

staged

方案已确定，等待实现

蓝色细框与 Staged · 待实现标签

outdate

已被新设计取代

柔和红框与 Outdate · 已过时标签

块级节点显示边框与标签；行内节点使用细下划线，outdate 为红色波浪线。cell 的边框沿格子内侧绘制，留出格间空隙。标注任意内容范围可使用带注解的显式 node；直接标注标题时，状态随标题属性归入 section。

样式来自共享的 status.css，静态站点与 Web 预览使用同一份 CSS，不需要 JavaScript。颜色使用宿主的 accent、surface、staged-color 与 outdate-color 变量；打印时边框为实线并去掉背景。属性输出规则见 HTML 属性与状态。

自身配置

文档声明自身的依赖，路径相对于当前文件：

#import "./lib.notc" as components;

正文用 #components.panel[...] 与 #components.badge("标签") 调用，组件资源放在声明文件所在目录。

组合示例使用 components.diagram，并直接导入 KaTeX。docs/Notist.toml 的数学映射独立导入 Typst，把内置 math 映射为 typst.math；文档中的直接 katex.math 调用仍使用 KaTeX。映射保持公式原文，不转换 Typst 与 LaTeX 方言。

Example

A simple inside a paragraph.

This content remains part of the document tree. Formula: .

Nested children retain their order and identity.

Pythagoras: . Direct module call: .

两个 panel 展示嵌套 children 与 expanded 参数；badge 展示大整数属性；diagram 使用配置选中的图形组件。内置调用和语法糖使用 Typst，直接 katex.math 调用使用 LaTeX。

草案内容与普通正文使用相同的排版；边框仅标识设计状态，不改变内容结构。

方案已确定，等待实现；内容状态由注解与 CSS 呈现。

已过时的设计保留原文，通过边框和状态标签标记。

段落中的 旧术语 BlockContent = Type{...} 使用红色波浪线，前后的文字保持行内排版。

状态说明
旧定义此行仅在 cell 内侧绘制边框。

构建与预览

在仓库根目录执行：

cargo run -p notist-cli -- check docs/components/README.not
cargo run -p notist-cli -- html docs/components/README.not --out-dir target/components-demo
python3 -m http.server

通过 HTTP 打开 /target/components-demo/。panel、badge 与状态样式无需构建步骤或 CDN；组合示例中由配置选择的图形组件、Typst 与 KaTeX 从固定版本 CDN 加载依赖。

Web 预览先构建 ./web/build.sh，通过 HTTP 打开 /web/，Vault 根 URL 为 ../docs/，输出配置为 Notist.toml，源码路径为 components/README.not，点击“载入项目”。

验证

web/tests/browser.cjs 验证此 Example 的静态页面、组件更新与重连、status 注解、项目预览、数学替换与模块诊断。运行前导出 target/components-demo 并构建 web/pkg，Playwright 须在 NODEPATH 上可用。NOTISTTESTURL 指定服务地址，NOTISTCHROMIUM 指定 Chromium 路径，NOTISTCOMPONENTSDEMO 可指定示例页面路径。

在相同的浏览器测试环境中执行 node web/tests/diagrams.cjs，验证同一正文通过配置切换 Pele / Mermaid、保留项目函数身份，并且无需加载声明本身的 Web Component。

web/tests/status.cjs 验证三种状态的块、行内与 cell 样式、嵌套内容、主题、窄屏、打印和无 JavaScript 呈现。运行前执行 cargo run -p notist-cli -- build --out-dir target/status-preview 并通过 HTTP 服务仓库；Playwright、NOTISTTESTURL 与 NOTIST_CHROMIUM 的约定相同。