Markdown Template (.mt)

.mt 是在 Markdown 基础上扩展了 @import 指令的文件格式。用它可以把本地文件、URL 上的内容动态拼接成一篇文档。本插件为 VS Code 提供 .mt 的语法高亮、实时预览（Markdown 渲染 / 展开后的纯文本两种模式）、源码 / 预览切换、复制与导出等能力。

功能一览

• @import 指令：相对路径、绝对路径、~、${workspaceFolder}、http(s) URL。
• 按类型处理：.md 等 markdown 文件直接合并；.json、.html 以及其它任何扩展名作为代码块引入，语言按扩展名识别；图片按图片引入。
• 参数：行范围、按标题引入、标题层级偏移、强制语言 / 强制代码块、可选引入。
• 嵌套引入：被引入的 markdown 内部可以继续 @import，相对路径以该文件自身目录为基准；自动检测循环引用与最大深度。
• 错误就地显示：文件不存在、URL 失败等在预览对应位置显示错误块，同时在“问题”面板中标红。
• 预览：侧边预览 / 当前编辑器预览、锁定 / 跟随活动编辑器、双向滚动同步、跟随 VS Code 主题、代码高亮。
• 两种渲染模式：Markdown 把展开后的文档渲染成 HTML；Code 把所有 @import 展开拼接后的文本原样显示（带行号，不做 Markdown 渲染，但像编辑器一样给标题、列表、链接、行内代码、代码块等做语法着色）。用预览顶部工具栏随时切换，两种模式都有滚动同步。
• 预览工具栏：预览顶部固定一条工具栏，集中放置“源码”、Markdown / 代码切换、刷新、锁定、复制、导出、界面语言按钮，带图标与文字，始终可见，不依赖面板是否获得焦点。
• 自动刷新：主文件与被引入文件（含未保存的编辑）变更后预览自动刷新；远程内容带缓存，刷新按钮可强制重新获取。
• 安全：预览 webview 使用严格 CSP，引入的 HTML 经净化，远程内容不执行脚本；不受信任的工作区禁用 URL 与工作区外路径。
• 编辑器：@import 路径自动补全、Ctrl/Cmd+点击跳转、代码片段、文件图标。
• 复制与导出：复制原始 .mt 源码、复制展开后的 Markdown、导出为 .md 文件。
• 界面语言：English / 中文，可独立于 VS Code 的显示语言切换（预览工具栏的语言按钮或命令），选择保存在 ~/.x1/adrive-studio/markdown-template/conf.yaml。
• 其它：多根工作区、Workspace Trust。

快速开始

1. 新建 demo.mt：

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

2. 点击编辑器右上角的预览图标，或按 Cmd/Ctrl+Shift+V（当前编辑器预览）、Cmd/Ctrl+K V（侧边预览）。

3. 在预览面板上按 Cmd/Ctrl+Shift+V 或点击预览顶部工具栏的“源码”按钮可切回源码。

4. 点击预览顶部工具栏的“代码”按钮切换到 Code 模式，看到的是把所有 @import 拼接后的纯文本（与“复制展开后的 Markdown”得到的内容一致）；点击“Markdown”按钮切回渲染模式。工具栏上还有刷新、锁定、复制、导出按钮。

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

@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.remote.enabled 与 mt.import.allowAbsolutePaths 会被强制关闭。

界面语言

界面内置 English、中文。默认跟随 VS Code 的显示语言；点击预览工具栏右侧的语言按钮，或执行命令 Markdown Template: 选择界面语言…，可随时切换，与 VS Code 的语言互不影响。切换后预览工具栏、面板标题、@import 错误提示、诊断与提示消息即时更新；命令标题、菜单项与设置说明由 VS Code 依据 package.nls.*.json 渲染，仍跟随 VS Code 的显示语言。

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

language: zh-cn   # 或 en

与其它 Markdown 插件的关系

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

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

此时本插件的预览、诊断等功能将不再对 .mt 生效。

开发

npm install
npm run compile      # 或 npm run watch
# 在 VS Code 中按 F5 启动扩展开发宿主，会自动打开 samples 目录
npm test             # 核心解析层单元测试
npm run package      # 生成 .vsix

代码结构：

• src/core/ 与 VS Code 无关的核心：指令解析、路径解析、展开器、远程缓存。
• src/renderer/ markdown-it 渲染（带源码行映射与代码高亮）；Code 模式的纯文本视图。
• src/preview/ 预览面板与管理器。
• src/features/ 诊断、文档链接、补全、命令。
• src/i18n.ts 扩展自己的界面语言（t()、语言列表、切换事件，不依赖 vscode）；src/confFile.ts 读写 conf.yaml。
• webview/ 预览页脚本（DOMPurify 净化、滚动同步）。
• docs/research/ 开发前对同类工具的调研记录。

License

MIT