Markdown

Notedeep Markdown 参考

文件属性

页面标签写在 `.md` 文首 YAML frontmatter，目录页写入 `_folder.md`。使用 `---` 围栏包围 `tags: [阅读, 产品]`，围栏各占一行。保留其他属性与注释，清空标签用 `tags: []`；不要写入 manifest 或 WorkspaceDoc。MCP 通过完整 Markdown 与页面 `baseVersion` 更新属性。

基础语法

  • 标题：`#` 到 `######`。
  • 段落：普通连续文本。
  • 空 block：独立一行 `<!-- notedeep:blank -->`，每个标记保留一个空 block；普通空行只分隔 block，不保留空 block。
  • 列表：`- item`、`1. item`，支持缩进嵌套。有序列表不保留起始编号，被图片等 block 打断后会从 1 重新编号；配图放在列表前后，不插在步骤之间。
  • Todo：`- [ ] item`、`- [x] item`。
  • 引用：`> quote`。
  • 代码块：三反引号加语言名，例如 ```` ```ts ````。
  • 表格：生成新内容时优先用 `:::table` + `--- row` / `--- cell`；标准 pipe table 和历史 HTML table 仅作为兼容输入。
  • 图片：兼容输入可用 `!alt`；需要保留宽高时用 `:::img`。
  • 行内：链接、粗体、斜体、粗斜体、公式 。
  • 本库页面链接使用相对 `.md` 路径；路径中的空格须写为 `%20`，否则可能显示成原始 Markdown。同步后核对公开页链接已解析到实际页面。
Notedeep Markdown 不是完整 CommonMark：当前不解析行内反引号代码、`~~删除线~~`、普通分隔线（如 `---`）、$tex$ / $tex$ 公式。代码用围栏代码块，公式用 （内容首尾不能有空白，内部美元符号写为 \$）；文首 `---` 仅用于 YAML frontmatter。

图片与附件

  • 写入 Markdown 前，必须先把本地图片或附件上传到云端。
  • MCP 返回 `https://www.notedeep.com/webapi/workspace-assets/...` 时，移除域名并使用 `:::img src="/webapi/workspace-assets/..."`。Desktop 本地通过该路径代理访问图片。
  • 不支持引用本地文件。禁止 `./assets/a.png`、`../a.pdf`、`/Users/...`、`C:\\...` 和 `file://...`。
  • 不要仅把文件复制到页面旁的 `assets/` 后写相对链接；`assets/` 中的文件只是上传源。
  • 图片使用 Notedeep MCP 上传；返回 URL 的转换与写入规则见 MCP 与图片上传。
  • 附件使用 MCP `create_attachment_upload` / `complete_attachment_upload`，完成后写入 `:::attach`；私有资源 URL 写入本地 Markdown 前移除域名，保留 `/webapi/workspace-assets/...`。

Directive 通用规则

:::{type} key="value"
body
:::
  • opening、body、closing 必须分行。
  • closing `:::` 必须独立一行，前后不能拼接文本。
  • attrs 只用双引号：`key="value"`。
  • 未知 type 会降级为普通文本；不要发明新 type。
  • body 是否解析 Markdown 由组件决定。

组件语法

table

用于普通二维表。生成新内容时优先使用 `:::table`，body 用 `--- row` / `--- cell` 分隔；cell 内继续写 Notedeep Markdown，可表达多个 block、空 block、嵌套自定义 block、`rowspan` 和 `colspan`。
:::table
--- row
--- cell
Name
--- cell
Value
--- row
--- cell rowspan="2"
A

- cell 内列表
- 仍然是 Notedeep Markdown
--- cell colspan="2"
<!-- notedeep:blank -->
:::
  • `--- row` 开启新行。
  • `--- cell [attrs]` 开启新单元格，并隐式结束上一个 cell。
  • `cell` attrs 只使用 `rowspan="n"`、`colspan="n"`。
  • 外层 table 仍统一用 `:::` 结束，不使用 `:::endtable`。
  • 标准 Markdown pipe table 和历史 `<table>...</table>` 仍可导入，但不要作为推荐生成格式。

img

用于保留图片 block 属性。`src` 必填，`alt`、`width`、`height` 可选；属性必须写在 opening 行。兼容导入仍支持 `!alt`，但标准 Markdown 图片不能表达宽高。
:::img src="/webapi/workspace-assets/workspace%2Fdemo%2Fimage.png" alt="demo" width="320px" height="180px"
:::

mermaid

用于 Mermaid 可表达的图：flowchart、sequenceDiagram、stateDiagram、classDiagram 等。
:::mermaid
flowchart TD
idea[Idea] --> plan[Plan]
plan --> build[Build]
:::

markmap

用于脑图，body 写 Markdown 层级。
:::markmap
# Product Plan
## Users
## Features
### Notes
### Search
:::

collapsible

用于折叠章节。body 会按 Notedeep Markdown 递归解析。
:::collapsible title="Details" open="true"
## Background
- Key fact 1
- Key fact 2
:::
兼容别名：`collapsible-panel`、`collapsible_panel`。生成新内容时优先用 `collapsible`。

info

用于提示块。`type` 可选：`info`、`warning`、`success`、`error`。body 会按 Notedeep Markdown 递归解析。
:::info type="warning"
## Notice
- Check this before publishing.
:::
兼容别名：`info-block`、`info_block`。生成新内容时优先用 `info`。

video

用于视频块。`src` 必填，`poster` 可选；属性必须写在 opening 行。
:::video src="https://static.notedeep.com/demo.mp4" poster="https://static.notedeep.com/demo.jpg"
:::

attach

用于附件块。常用属性：`src`、`name`、`type`、`size`；属性必须写在 opening 行。
:::attach src="https://static.notedeep.com/report.pdf" name="report.pdf" type="application/pdf" size="123456"
:::

diagram

用于 draw.io。body 放原始 draw.io XML；历史 JSON `{"xml":"..."}` 可被兼容读取，但生成新内容时用 XML。
:::diagram
<mxfile host="embed"><diagram id="diagram" name="Page-1"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>
:::

whiteboard

用于 Excalidraw 白板。body 必须是有效 JSON。
:::whiteboard
{"scene":{"elements":[],"appState":{},"files":{}}}
:::

drawnix

用于可视化编辑的脑图与画布。body 保存 Drawnix 原生 JSON，`children` 是画布元素，已有 `viewport`、`theme` 须保留；不要套用 Excalidraw 的 `scene` 结构。
:::drawnix
{"children":[]}
:::
这是空画布示例。已有内容应保留完整 JSON；导入时原样保存源码，格式错误会导致预览报错。

smart_table

用于智能表格、数据库、甘特图。body 是 Notedeep smart table data HTML；普通二维表优先用 `:::table`。
:::smart_table
<script type="application/json" class="smart-table-fields">
[
{"id":"f1","name":"Task","type":"text"},
{"id":"f2","name":"Start","type":"date"},
{"id":"f3","name":"End","type":"date"}
]
</script>
<script type="application/json" class="smart-table-view-gantt">
{"startFieldId":"f2","endFieldId":"f3","titleFieldId":"f1"}
</script>
<div class="smart-table-rows">
<script type="application/json" class="smart-table-row" data-row-id="r1">
{"id":"r1","cells":{"f1":{"value":"Example Task"},"f2":{"ymd":"2026-05-25"},"f3":{"ymd":"2026-05-26"}}}
</script>
</div>
:::
兼容别名：`smart-table`、`smarttable`。生成新内容时优先用 `smart_table`。

html

用于静态 HTML/CSS。body 原样保存并在 sandbox iframe 中展示，不执行用户 JavaScript。
:::html
<section style="padding:24px">
<h1>Title</h1>
</section>
:::

likec4

用于软件技术架构模型。一个 block 的 body 保存完整 LikeC4 DSL，可以在 `views` 中定义多个 view；opening 行的 `view` 指定默认视图。
参考资料：https://likec4.dev/llms.txt
:::likec4 view="overview"
specification {
element system
}
model {
app = system 'Application'
}
views {
view overview {
include *
}
}
:::
  • body 必须是完整、可编译的 LikeC4 DSL。
  • `view` 应引用 body 中已经定义的 view id。
  • 不要把每个 view 拆成单独 block。

archify

用于 Archify 交互图。使用 `:::archify` 起始行、完整 JSON body、独立的 `:::` 结束行；无专用 attrs。`diagram_type` 支持 `architecture`、`workflow`、`sequence`、`dataflow`、`lifecycle`。
格式参考：官方 schema 说明、官方完整 JSON 示例（与当前 Notedeep 内置版本一致）。
选择对应类型的完整 JSON 示例，按该类型 schema 与 common.schema.json 修改，不能仅填 diagram_type 或猜测字段。已有 block 保留完整 JSON，不嵌入编译后的预览 HTML。