Markdown Template (.mt)

.mt 是在 Markdown 基础上扩展了 @import 指令的文件格式。用它可以把本地文件、URL 上的内容动态拼接成一篇文档。本插件为 VS Code 提供 .mt 的专属编辑页：在同一个页面里编辑源码、查看所有 @import 展开后的组装结果、查看渲染效果，并支持格式化、标题编号、复制与导出。

功能一览

• 专属编辑页：打开 .mt 文件直接进入插件自己的编辑页，顶部工具栏切换三种视图：
  • 源码：编辑 .mt 原文。Markdown 语法高亮（含围栏代码块里的 JSON、JS/TS、HTML、YAML、SQL、Python、Java 等语言），@import 指令单独着色；
  • 组装：把所有 @import 就地展开后的纯文本，带行号与语法着色（与“复制展开后的 Markdown”得到的内容一致）；
  • 渲染：把组装结果渲染成 HTML，代码高亮、图片、链接都可用。
• 格式化：源码视图一键格式化（Prettier），@import 指令行原样保留；格式化后渲染结果不变才会写回。
• 表格对齐：源码视图一键按列对齐所有 Markdown 表格（中文按两个字符宽计算）；源码视图里表格中的中文按正好两个英文字符宽显示，补齐的表格能真正竖直对齐；表格上右键可在上方 / 下方插入对齐好的空行。
• 表格分段：表格中间整行为空的一行渲染为分段间隔，长表可以按含义分组，各段列宽一致。
• 标题编号：源码、组装、渲染三种视图的标题前都自动显示编号 1 标题、1.1 标题、1.1.1 标题，被引入文件里的标题一起编号；编号只是显示，不能手工修改。
• 导航：左侧面板分【导航】【批注】两页：导航按标题生成目录，批注列出全文批注；三种视图都可以点击快速定位，滚动时高亮当前所在标题。
• 批注：用 %%批注%% 写批注（多行批注用单独一行的 %% 包起来）；源码、组装视图里高亮，渲染视图显示成黄色标签；源码视图右键【添加批注】；复制与导出时自动去掉。
• @import 指令：相对路径、绝对路径、~、${workspaceFolder}、http(s) URL。
• 按类型处理：.md 等 markdown 文件直接合并；.json、.html 以及其它任何扩展名作为代码块引入，语言按扩展名识别；图片按图片引入。
• 参数：行范围、按标题引入、标题层级偏移、强制语言 / 强制代码块、可选引入。
• 嵌套引入：被引入的 markdown 内部可以继续 @import，相对路径以该文件自身目录为基准；自动检测循环引用与最大深度。
• 错误就地显示：文件不存在、URL 失败等在源码视图里标红波浪线、在渲染视图对应位置显示错误块，同时出现在“问题”面板中。
• 编辑体验：@import 路径自动补全、Cmd/Ctrl+点击打开被引入的文件、查找替换（支持正则、仅选中区域）、git 行变化提示、VS Code 风格快捷键与多光标、字体跟随 VS Code。
• 语法配色跟随颜色主题：源码视图、组装视图与代码块的语法颜色取自当前 VS Code 颜色主题（如 Monokai Pro），与文本编辑器里看到的一致。
• 与 VS Code 一致的文档行为：撤销 / 重做、保存、未保存标记、热退出都走 VS Code 自己的机制；同一文件同时开着多个编辑页或文本编辑器时内容实时同步；外部修改（git、其它编辑器）合入时光标不跳。
• 自动刷新：主文件与被引入文件（含未保存的编辑）变更后组装 / 渲染视图自动刷新；远程内容带缓存，刷新按钮可强制重新获取。
• 安全：编辑页使用严格 CSP，引入的 HTML 经净化，远程内容不执行脚本；不受信任的工作区禁用 URL 与工作区外路径。
• 复制与导出：复制原始 .mt 源码、复制展开后的 Markdown；导出为 .mt 同目录下的同名 .md（组装结果）或 .html（渲染结果，样式内联、可直接用浏览器打开）文件。
• 界面语言：中文、English、Deutsch、Français、日本語、한국어、Русский，默认 English，可独立于 VS Code 的显示语言切换（工具栏的语言按钮或命令），选择保存在 ~/.x1/markdown-template/conf.yaml。
• 其它：多根工作区、Workspace Trust；需要时可随时退回 VS Code 自己的文本编辑器。

快速开始

1. 新建 demo.mt：

   # 我的文档
   
   @import "parts/intro.md"
   @import "data/config.json"
   <!-- @import "parts/page.html" -->
   

2. 打开它，默认进入专属编辑页的 源码 视图，直接编辑即可（Cmd/Ctrl+S 保存）。

3. 点击工具栏的 组装 查看所有 @import 拼接后的纯文本，点击 渲染 查看渲染效果；Cmd/Ctrl+E 在三种视图之间循环，Cmd/Ctrl+Shift+V 在源码与渲染之间切换。

4. 在组装 / 渲染视图里双击某一段，跳回源码对应行。

仓库中的 samples/demo.mt 演示了全部语法。

专属编辑页

工具栏

导航

工具栏最左边的 导航 按钮打开左侧面板。面板顶部是 导航、批注 两个页签（占满宽度的分段按钮，带图标；批注页签上显示批注数量，选中哪一页随编辑页记住）。导航页按标题生成文档目录，点击即可定位：

• 源码 视图列出 .mt 原文里写的标题，边写边更新；组装 视图列出所有 @import 展开后的标题（包括被引入文件里的）；渲染 视图列出渲染后的标题；
• 每个标题前带上与视图里一致的编号；
• 文件在 git 仓库里时，有改动的章节在标题右侧标一个圆点（章节指标题到下一个标题之前的内容），颜色与行号旁的提示一致：绿色新增、蓝色修改（只标新增与修改，删除不标；改了标题本身也算这一节有改动），已暂存的更改颜色较淡；只有子章节有改动的上级标题标空心圆，折叠起来也能看出哪一章有改动。改动随输入、暂存、提交实时更新；组装 / 渲染视图里 .mt 自己的标题同样标出，被引入文件里的标题不标；
• 支持 # 标题 与 === / --- 下划线两种写法；front matter、围栏代码块、引用块与列表里的 # 不算；
• 按层级缩进成树，有子标题的项可以单独折叠；
• 页签右边的 1 / 2 / 3 把整棵树展开到第几级（之后新出现的标题也照此折叠），+ 全部展开；
• 滚动时高亮当前所在的标题，并让它保持在面板可见范围内；
• 拖动面板右边缘调整宽度，双击恢复默认；面板开关与宽度记在 conf.yaml，所有编辑页通用；
• 键盘：↑ ↓ 移动，Enter 定位，← 折叠或回到上一级，→ 展开。

批注页列出当前视图里的全部批注，每条一张卡片（内容只显示一行，完整内容见悬停提示；下面一行黄色字是所在章节的编号与标题），点击跳到那一处：源码视图选中这条批注，组装 / 渲染视图滚到那里并闪一下。组装 / 渲染视图里也包括被引入文件中的批注。

导出

工具栏的 导出 是一个下拉菜单，两种导出都直接写到 .mt 所在目录，文件名与 .mt 相同（demo.mt → demo.md / demo.html），已存在的同名文件会被覆盖：

• Markdown 文件：保存组装后的 Markdown，与“组装”视图、“复制”得到的内容一致；
• HTML 文件：保存渲染后的页面。一个独立的 .html，样式内联（浅色，系统深色模式下自动换深色），代码高亮、表格、图片都保留；图片与链接沿用相对 .mt 所在目录的路径，因此导出文件与 .mt 放在一起时可以直接用浏览器打开。字体取 mt.preview.* 设置，带标题编号。

Markdown 里写的原始 HTML 在导出文件中原样保留：编辑页显示时会做净化，导出的 .html 不做这一步，引入了不可信的远程内容时请留意。

导出的是编辑页里当前的内容（包括尚未保存的修改）。@import 出错时照常导出（Markdown 里是一行注释，HTML 里是错误块），并提示问题个数。未命名的 .mt 没有所在目录，会改为弹出保存对话框。

快捷键

快捷键都可以在 VS Code 的“键盘快捷方式”里修改（命令前缀 Markdown Template:）。

查找替换

源码视图按 Cmd/Ctrl+F 打开查找面板，支持区分大小写、正则表达式、全字匹配，以及 仅选中区域：

• 勾上 仅选中区域（或按 Cmd+Alt+L / Ctrl+Alt+L）后，查找、高亮、替换、全部替换、全部选中都只在勾选那一刻的选区里进行；查找范围用底色标出，之后选区跳到各个匹配，范围不变。不勾就是全文查找替换；
• 选中多行后再按 Cmd/Ctrl+F，自动勾上并以选区为范围（选中文字不填进查找框）；只选中一行内的文字时照旧把它填进查找框；
• 没有选中内容时勾选，范围是光标所在行；多个选区（多光标）各自成为一段范围；
• 关闭查找面板即取消范围。

在查找框按 Tab 跳到替换框，替换框按 Shift+Tab 跳回查找框；查找框里 Enter / Shift+Enter 查找下一个 / 上一个，替换框里 Enter 替换当前匹配。

git 行变化提示

文件在 git 仓库里时，源码视图与 VS Code 文本编辑器一样显示行变化：

• 行号右侧：竖条为新增 / 修改过的行，三角表示该处删除了内容（颜色随主题）；已暂存的更改用另一种颜色（主题的 editorGutter.*SecondaryBackground，主题没有定义时为同色半透明）；
• 滚动条左侧：与 VS Code 一样，把整篇文档的每一处变化按位置比例画在右侧的标记条上（行号旁只显示眼前这几行），颜色与行号旁的竖条相同，已暂存的更改颜色较淡；点击标记跳到那一处。标记条紧挨在滚动条左边、不与滚动条重叠（源码视图的滚动条固定占 10px，不随 macOS 浮动滚动条隐藏）；
• 点击竖条：在这处更改下方展开内嵌差异窗口，红色为原来的行、绿色为现在的行；标题栏可以切换上一处 / 下一处，暂存更改（只把这一块写入暂存区，不动工作区文件）、还原更改（把这几行改回暂存区里的内容，可以撤销），再点一次竖条或按 Esc 关闭；已暂存的更改只显示差异；
• 键盘：Alt+F3 / Shift+Alt+F3 打开下一处 / 上一处更改的差异窗口，Alt+F5 / Shift+Alt+F5 把光标移到下一处 / 上一处更改。

规则与 VS Code 一致：

• 未暂存的更改是当前内容与 git 暂存区（index）比较的结果，已暂存的更改是与 HEAD 比较的结果，同一行两者都有时按未暂存显示；未跟踪、被忽略、有合并冲突的文件不显示；
• 当前内容包括尚未保存的修改，输入时实时更新；暂存、提交、切换分支或在外部执行 git 操作后自动刷新；
• 遵循 VS Code 的设置：scm.diffDecorations（gutter 只显示行号旁、overview 只显示滚动条上、none 都不显示）、scm.diffDecorationsGutterWidth（竖条宽度）、scm.diffDecorationsGutterVisibility（hover 时鼠标移到行号区才显示）；
• 通过 VS Code 内置的 git 扩展读取与暂存，git 扩展被禁用时不显示。

与文本编辑器的关系

• 文件内容就是 VS Code 的文本文档：撤销 / 重做（包括“编辑”菜单）、保存、自动保存、未保存标记、热退出都与普通文件一致。连续输入约半秒合并为一步撤销。

• 想用 VS Code 自己的文本编辑器（例如需要 Vim、Copilot 等扩展）：点工具栏的 文本编辑器，或执行命令 用文本编辑器重新打开；在文本编辑器里点标题栏的图标或执行 用 Markdown Template 编辑器打开 可以切回来。

• 想让 .mt 默认用文本编辑器打开，在设置里加：

  "workbench.editorAssociations": { "*.mt": "default" }
  

  这时 Cmd/Ctrl+Shift+V（在当前位置打开渲染视图）与 Cmd/Ctrl+K V（在侧边打开渲染视图，跟随文本编辑器滚动）仍然可用。

• Git 对比、合并视图里的 .mt 仍然用文本 diff 显示。

• 同一个文件可以同时在两栏打开（例如左边源码、右边渲染），滚动会互相跟随（设置 mt.preview.scrollPreviewWithEditor / mt.preview.scrollEditorWithPreview）。

格式化

格式化使用 Prettier（Markdown），规则包括：块与块之间补一个空行、列表符号统一为 -、表格按显示宽度对齐（中文按两个字符宽）、去掉行尾空白；中英文之间不插空格，段落内的换行保持原样，代码块内容不动。嵌套列表的缩进跟随编辑器为 .mt 设置的 editor.tabSize。

• @import 指令行（含注释形式与 \@import 转义行）原样保留，紧贴在上一行之后的写法也保持不变。
• 写回前会校验：指令序列不变、渲染结果不变；任一不满足就不改动文档，并给出提示。
• 不想被格式化的部分可以用 <!-- prettier-ignore -->（下一个块）或 <!-- prettier-ignore-start --> … <!-- prettier-ignore-end --> 包起来。
• 文本编辑器里的“格式化文档”、editor.formatOnSave 用的是同一套实现。

语法配色

源码视图、组装视图以及渲染视图里代码块的语法颜色，取自当前的 VS Code 颜色主题：插件读取主题文件里的语法配色（含主题 include 的其它主题文件），叠加设置 editor.tokenColorCustomizations，按 VS Code 文本编辑器同样的作用域规则给标题、列表符号、链接、@import 关键字 / 路径 / 参数、代码里的字符串与关键字等算出颜色和字形。所以同一个主题下，专属编辑页与文本编辑器的颜色一致；切换主题后立即跟着变。

以 Monokai Pro 为例：标题黄色、# 与列表符号灰色、@import 粉色、路径绿色带下划线、参数名青色斜体。

个别主题的语法配色是旧的 .tmTheme 格式，读不到时使用内置的配色（贴近 Light+ / Dark+）。

表格对齐

源码视图工具栏的 表格对齐 按钮（或命令 Markdown Template: 表格对齐，文本编辑器里也能用）把文档里的所有表格按列对齐：

| 字段名称         | 字段类型          | 字段备注     |
|------------------|-------------------|--------------|
| record_id        | bigint not null   | 记录ID       |
| product_name_raw | character varying | 产品名称原文 |

• 单元格按显示宽度补空格，中文、全角标点算两个字符宽；
• 已经对齐的表格原样保留（包括特意留宽的列），没对齐的表格按内容重排成最紧凑的宽度；
• 保留每列的对齐方式（:--- / ---: / :---:）与分隔行的写法（|-----| 或 | --- |）；
• 只改表格，其它内容不动，一步撤销即可还原；围栏代码块里的表格不处理。

等宽字体里的汉字一般比两个英文字符略窄，所以即使补齐了空格，普通编辑器里中文表格也会越往右越错位。源码视图对表格做了专门处理：表格里的中文按正好两个英文字符宽显示（字间距会略宽一点），表格行不自动换行，过长时横向滚动。正文段落不受影响。

整篇 格式化（Prettier）同样会对齐表格，但分隔行统一写成 | --- |；喜欢 |-----| 写法的话，只用 表格对齐 即可。

插入表格行

源码视图里在表格上点右键，菜单里有 ↑ 上方插入空行、↓ 下方插入空行：

• 插入的是表格的一行空单元格，列数与表格相同，| 按列对齐；光标放进新行的第一格；
• 在表头或分隔行上只有 下方插入空行，插为第一行数据；
• 已对齐的表格只多出新的一行；没对齐的表格插入后整张表一起对齐（规则同“表格对齐”）；一步撤销即可还原。

表格分段

表格中间所有单元格都为空的一行，渲染时当作分段间隔：表格在这里断开，空行处没有竖线上下相连，但上下各段仍是同一个表格，列宽保持一致。适合把一张长表按含义分组：

| 字段名称                     | 字段类型          | 字段备注         |
|------------------------------|-------------------|------------------|
| flow_basic_manual_message    | character varying | 基础信息整编消息 |
| flow_basic_manual_body       | jsonb             | 基础信息整编内容 |
|                              |                   |                  |
| flow_subject_deepseek_status | character varying | 学科信息提取状态 |

• 渲染视图与导出的 HTML 都按此显示；源码、组装视图与导出的 .md 保持原文；
• 只要有一个单元格有内容就是普通行；确实需要一个空白数据行时，在任一单元格里写  ；
• 表格对齐、格式化都会保留这种空行。

标题编号

三种视图的标题前都自动显示编号，编号与标题文字之间有一个空格；导航面板里的标题也带同样的编号：

1 一级标题
1.1 二级标题
1.1.1 三级标题

• 源码、组装视图里编号显示在 # 与标题文字之间（## 1.1 标题），Setext 写法显示在文字之前；
• 以文档中出现的最高级标题为一级（整篇从 ## 开始时，## 就编为 1）；
• 跳级时缺的一级补 0（# 之后直接 ### 显示为 1.0.1）；
• 组装后的整篇文档统一编号，被引入文件里的标题也参与（源码视图里看不到被引入的标题，编号会相应跳过），三种视图的编号一致；引用块、列表里的标题不参与；
• 编号自动生成，只是显示：不能手工修改，源码里光标会跳过它；复制、保存、导出的 .md 都不带编号，标题锚点与 #章节 引入不受影响；导出 HTML 带编号。

批注

用两个百分号把批注包起来；多行批注用单独一行的 %% 开始和结束：

价格 100 元%%待财务确认%%，含税。

%%
这一节的数据口径
下周再核对
%%

• 源码视图：批注加淡黄底色；在正文上点右键选 ✎ 添加批注，在光标处（有选中文字时在选中文字之后）插入 %%%%，光标停在中间，直接输入批注内容；
• 组装视图：同样加底色，被引入文件里的批注也一样；
• 渲染视图：显示成黄色标签，多行批注显示成一整块，批注内容按纯文本显示（不解析 Markdown）；
• 复制、导出 .md、导出 HTML：自动去掉批注；一行里只有批注时整行去掉，不会把段落拆开；
• 格式化不改动批注内容；标题里的批注不算标题文字（不进导航、锚点）；多行批注里的 # 不是标题；
• 行内批注不能跨行，内容不能全是空白；\%%、行内代码与围栏代码块里的 %% 不算批注；只有开始没有结束的 %% 照原文显示。

@import 语法

@import "path/to/file.md"
@import 'path/to/file.json'
@import path/to/file.ts
@import "path/to/file.md" {line_begin=2 line_end=10}
<!-- @import "path/to/file.md" -->

• 指令必须独占一行，可以有前导空白，行尾可加 ;。
• 路径可用双引号、单引号或不加引号（不加引号时不能含空格）。
• <!-- @import "..." --> 注释形式与普通形式等价，好处是用其它 Markdown 工具打开 .mt 时它会被当成注释而不显示。
• 围栏代码块内的 @import 不会被处理；行首写 \@import 可输出字面量。

路径

路径中的空格可以直接写在引号里，也可以写成 %20；文件名里的 # 写成 %23。

文件类型

参数

写在行尾的 {} 中，多个参数用空格分隔：

示例：

@import "src/main.ts" {line_begin=10 line_end=-1}
@import "docs/api.md#认证" {heading_offset=1}
@import "notes.txt" {as="markdown" code_block=false}
@import "https://github.com/microsoft/vscode/blob/main/README.md" {line_end=5}

命令

配置

插件还为 .mt 设置了几项编辑器默认值（与 VS Code 对 Markdown 的默认一致）：自动换行开启，不给中文标点等“易混淆字符”加框。可以在设置里用 "[mt]": { ... } 覆盖。

在不受信任的工作区中，mt.remote.enabled 与 mt.import.allowAbsolutePaths 会被强制关闭。

界面语言

界面内置 中文、English、Deutsch、Français、日本語、한국어、Русский 七种语言。默认 English，不跟随 VS Code 的显示语言；点击编辑页工具栏右侧的语言按钮，或执行命令 Markdown Template: 选择界面语言…，可随时切换，与 VS Code 的语言互不影响。切换后编辑页工具栏、源码视图的查找面板、@import 错误提示、诊断与提示消息即时更新；命令标题、菜单项与设置说明由 VS Code 依据 package.nls.*.json 渲染，仍跟随 VS Code 的显示语言（这七种语言都提供了对应的 nls 文件）。

选择保存在 ~/.x1/markdown-template/conf.yaml，也可以手工编辑：

language: zh-cn        # en / de / fr / ja / ko / ru / zh-cn
outline: true          # 是否显示左侧导航面板（工具栏“导航”按钮会写这一项）
outlineWidth: 240      # 导航面板宽度（像素，140～600；拖动面板边缘会写这一项）

与其它 Markdown 插件的关系

.mt 注册为独立语言 mt，因此 Markdown All in One 等只对 markdown 语言激活的插件默认不会作用于 .mt。如果你更需要那些插件，可以在设置中把 .mt 关联回 markdown：

"files.associations": { "*.mt": "markdown" }

此时本插件的诊断、路径补全、格式化等语言功能不再对 .mt 生效（专属编辑页仍然可用）。如果也不想用专属编辑页，再加上 "workbench.editorAssociations": { "*.mt": "default" }。

开发

npm install
npm run compile      # 或 npm run watch
# 在 VS Code 中按 F5 启动扩展开发宿主，会自动打开 samples 目录
npm test             # 单元测试（解析、展开、格式化、标题编号、文档同步等，不依赖 VS Code）
npm run package      # 生成 .vsix

代码结构：

• src/core/ 与 VS Code 无关的核心：指令解析、路径解析、展开器、远程缓存、文本最小差异、行列换算。
• src/renderer/ markdown-it 渲染（带源码行映射、代码高亮、标题编号）；组装视图的纯文本渲染。
• src/format/ 格式化（Prettier + @import 指令保护与校验），单独打包为 dist/formatter.js，第一次格式化时才加载。
• src/editor/ 专属编辑页：自定义编辑器 provider、单个编辑页（文档同步、展开渲染、链接）、页面 HTML 与工具栏、与 webview 的消息协议。
• src/features/ 诊断、文档链接、补全、格式化 provider、命令。
• src/i18n.ts 扩展自己的界面语言（t()、语言列表、切换事件，不依赖 vscode）；src/confFile.ts 读写 conf.yaml。
• webview/editor/ 编辑页脚本：源码视图（CodeMirror 6、@import 语法、文档同步）、组装 / 渲染内容区（DOMPurify 净化、滚动定位）、工具栏。

License

MIT