^VLOOK™
快速参考手册 Quick Reference Manual
──

# 版本丨V9.11 #




MAX丨孟兆
COPYRIGHT © 2016-2020. MAX°DESIGN.

VLOOK™ 是什么

最新版本丨V9.11 + 官网丨https://github.com/madmaxchow/VLOOK + * 适用平台丨Typora for Win & macOS * - 开源协议丨MIT - ! 开发语言丨JavaScript !

VLOOK™ 是针对由Typora¹（目前最好的跨平台 Markdown 编辑器，没有之一）导出的 HTML 文件进行增强的插件。

VLOOK™ 为开源软件，遵从 MIT 许可证。

[-] Markdown 是什么？

• 2004年，John Gruber 创造了 Markdown，一种专门针对网络写作的文本标记语言。使用 Markdown，你只需在写作过程中插入少量的标记符号，就能很轻松地进行排版（例如设置标题、加粗、列表、引用等）。
• Markdown文档以纯文本格式存储，这意味着，它们可以用几乎任一种文本编辑器打开。同时，又能通过 Markdown 编辑器导出为带排版的富文本文档、HTML 网页等等。纯粹、简洁、易用、灵活，都是人们喜欢 Markdown 的原因。
• 目前 Markdown 的标准化项目是 CommonMark。

[+] Markdown 语法：

1. 标准化 CommonMark 语法参考：60秒学会 Markdown 语法、10 分钟深入学习 Markdown
2. GitHub 采用 Flavored Markdown 的语法参考：Typora 目前采用该标准 详细

特性清单

VLOOK™ 针对 Markdown 的短板，以及在实际众多的文档排版、导航、演示、交互需求中寻找平衡点，为 Markdown 的编辑者和阅读者提供了更好的使用体验。

![VLOOK™ 特性清单]"环境要求：VLOOK V9.7+，Typora mac版 V0.9.9.31+ / Win版 V0.9.83+"

特性介绍

排版增强

多主题样式

• 针对 VLOOK 内置多套优化的主题样式²（在导出 HTML 通过 Typora 的「主题」菜单选择名称以 VLOOK 打头的主题）；

  • Hope 海洋之心：预览 ＞
  • Joint 榫卯：预览 ＞
  • Geek 极邃：预览 ＞
  • Fancy 慕幻：预览 ＞

• 所有主题的文档导出为 HTML 后，都支 Dark 模式；

• 提供主题的私人定制服务（私人定制服务微信：MaxChow），定制样品示例如下：

封面、封底

封面

• 封面样式支持多个信息项，包括：标题、文档类型/密级、作者、版权信息；

• 封面必须以6级标题作为整篇文章的第1个章节，同时各信息项的顺序与格式规则建议如下（可视实际需要自行调整）：

  • 标题：无须指定格式标记，直接输入

  • 文档类型/密级：支持使用 Markdown 的代码格式标记`，同时支持 VLOOK 的双标签风格写法，应用举例如下：

    • + 文档密级丨对外公开 +
    • * 文档密级丨内部公开 *
    • - 文档密级丨机密资料 -

  • 作者：使用粗体格式标记**作者**（插件会自动增加by前缀）

  • 版权信息：使用 Markdown 的斜体格式标记*版权信息*

• 样式见本文的封面，完整示例参考如下（其中<br>为换行符号，可选）：

  xxxxxxxxxx
  1
  1
  ### 此处为标题1<br>此处为标题2<br><br><br><u>此处为作者姓名</u><br>*此处为版权信息*
  

封底

• 以最后一个6级标题作为封底；

• 样式见本文的封底，完整示例参考如下：

  xxxxxxxxxx
  1
  1
  ###### 此处为封底
  

标题、插图、表格、表格行自动编号

• 标题自动编号：

  • 自动对 1级 ~ 5级 标题进行自动编号；
  • 6级 标题在 VLOOK 中应用于封面和封底、分段排版等，不在自动编号范围内。

• 插图自动编号：

  • 对所有插图，包括图片、mermaid 图进行统一的自动编号。

• 表格、表格行自动编号：

  • 在表格自动编号会在以下两种情况下生效：
  • 在列表（注意表格要缩进）下：

  列1	列2	列3	列4
  第一行	左对齐（长内容）	居中对齐	右对齐（长内容）
  第二行（长内容）	左对齐	居中对齐（长内容）	右对齐

  子表（这是一个缩进的6级标题）

  ![这是表格第1题注]"这是表格第2题注"

  列1	列2	列3	列4
  第一行	左对齐（长内容）	居中对齐	右对齐（长内容）
  第二行（长内容）	左对齐	居中对齐（长内容）	右对齐

  在1级 ~ 6级标题下：

这是6级标题

自动生成插图、表格的题注

• 自动为文档内的所有插图、表格添加题注；

• 插图、表格支持多个题注，第1个题注默认在上方，第2上题注在下方。

  • 普通图片：查看示例

    • 以图片标题为第 1 题注，如：![第1题注内容](图片URL)
    • 以 URL 后的标题为第 2 题注，如：![第1题注内容](图片URL "第2题注内容")
    • 第 2 题注内容为可选。

  • mermaid 图：查看示例

    • 在图表前增加题注描述，这里的语法是 VLOOK 扩展的 Markdown 语法；
    • 语法：`![第1题注内容]"第2题注内容"，其中的「第 2 题注」内容同样为可选；
    • 该原始内容会在应用VLOOK插件后被隐藏，如在1级 ~ 5级标题中应用，并要保留原始标题内容，可加起一行进行描述。

  • 表格：查看示例

    • 同「mermaid 图」。

表格单元格合并

• 列合并：直接填写三个英文等号==进行标识；
• 行合并：直接填写三个英文句号..进行标识，并支持列头跨行合并。

- 注意 -该特性须导出 HTML 并注入 VLOOK 插件后才能生效。

单元格合并示例

![示例一：单元格并列合并、行合并]"注：须使用最新版的 Typora 和 VLOOK"

![示例二：表头跨行合并1]

![示例三：表头跨行合并2]

表格列格式设置

• 对表格的任意列统一格式，支持的格式包括：**加粗**、*斜体*、<u>下划线</u>、==高亮==、~~删除线~~；
• 参考以上形式，只须在表头按标准的 Markdown 语法设置对应的格式即可实现整列格式化（暂不支持多格式的嵌套）。

- 注意 -该特性须导出 HTML 并注入 VLOOK 插件后才能生效。

示例效果

彩虹标签

对于 Markdown 的行内代码标记` ，通过特定的扩展标识，来用不同的样式渲染指定的代码标签实现彩虹标签效果。

- 注意 -因 Typora 的原因，暂不提供在编辑时进行实时预览，样式效果须导出 HTML 并注入 VLOOK 插件后才能生效。

单标签风格

• 通过在行内代码内容前增加扩展标识的内容来标记；

• 可用于文档中例如修订记录说明、界面元素（按钮、标签）说明、突出标记等，应用举例如下：

  • + 新增 +本次修订新增XXX功能
  • * 优化 *本次修订删除XXX功能
  • 用户点击# 立即购买 #后进入XXX页面
  • - 注意 -有关的注意事项说明

• 详细规范如下（文本内容前后须加空格）：

  扩展标识示例	色调	渲染效果
  `= 文本内容 =`	蓝	= 文本内容 =
  `+ 文本内容 +`	绿	+ 文本内容 +
  `* 文本内容 *`	橙	* 文本内容 *
  `- 文本内容 -`	红	- 文本内容 -
  `! 文本内容 !`	紫	! 文本内容 !
  `# 文本内容 #`	灰	# 文本内容 #

双标签风格

• 目前支持药丸式的两段结构，可用于例如版本号说明、变量说明等，例如：

  • = 版本号丨V1.0.2 =
  • ! X取值丨1234 !
  • - 优先级丨高 -

• 可支持多种样式，举例如下：

  写法示例	色调	渲染效果
  `= 样式类型丨样式1 =`	蓝	= 样式类型丨样式1 =
  `+ 样式类型丨样式2 +`	绿	+ 样式类型丨样式2 +
  `* 样式类型丨样式3 *`	橙	* 样式类型丨样式3 *
  `- 样式类型丨样式4 -`	红	- 样式类型丨样式4 -
  `! 样式类型丨样式5 !`	紫	! 样式类型丨样式5 !
  `# 样式类型丨样式6 #`	灰	# 样式类型丨样式6 #

• 旧语法，举例如下：

  写法示例	色调	渲染效果
  `样式类型丨样式1`	蓝	样式类型丨样式1
  `样式类型丨丨样式2`	绿	样式类型丨丨样式2
  `样式类型丨丨丨样式3`	橙	样式类型丨丨丨样式3
  `样式类型丨丨丨丨样式4`	红	样式类型丨丨丨丨样式4
  `样式类型丨丨丨丨丨样式5`	紫	样式类型丨丨丨丨丨样式5
  `样式类型丨丨丨丨丨丨样式6`	灰	样式类型丨丨丨丨丨丨样式6

+ 提示 +其中的竖线符号可用英文半角竖线符号并前后加空格<空格>|<空格>，或中文笔划（竖）丨或全角竖线符号｜。

mermaid 样式优化

• 统一优化 mermaid 图的样式，并自动适配 Dark 模式下的呈现；
• 同时修正因 mermaid 原因，在不同操作系统和浏览器下的兼容性问题；
• 更多脚本化图表样式，以及结合 VLOOK 相关的脚本编写规范内容详见《脚本化图表 for Markdown》。

mermaid－流程图

![流程图]"（以上的「分支流程」内容由下图进行接续）"

![分支流程（接续上图）]

mermaid－状态图

mermaid－时序图

- 注意 -因 Typora 的原因，部分特性暂不提供在编辑时进行实时预览，须导出 HTML 并注入 VLOOK 插件后才能生效。

统一多级列表编号

• 对所有有序、无序的多级列表编号进行统一编号符号。

列表分级编号样式预览：

• 一级列表内容

  • 二级列表内容

    • 三级列表内容

      • 四级列表内容

        • 五级列表内容

          • 六级列表内容

• 用 Markdown 编写参考如下（任意写法均可），每级缩进2个空格：

  xxxxxxxxxx
  9
  1
  - 一级列表内容
  2
     - 二级列表内容
  3
       - 三级列表内容
  4
         - 四级列表内容
  5
           - 五级列表内容
  6
             - 六级列表内容
  7
  1. 一级列表内容
  8
     + 二级列表内容
  9
       - 三级列表内容
  

任务列表支持自动编号

• 在任务列表前保留原始有序/无序列表信息；

• 勾选按钮样式为正常样式，同时保持为不可点击；

• 示例：这是一级样式

  • 这是二级样式

  • 这是已选中的二级样式

文档导航

大纲导航

• 支持页面左侧显示目录大纲，并能根据页面位置自动高亮当前章节；
• 可对章节进行折叠/展开。

- 注意 -编写 Markdown 文档时，须在封面后添加标签[TOC]。

逐章导航

• 支持在页面顶部显示当前章节标题内容（除第6级标题），在封面时自动收起；
• 根据页面位置自动识别当前章节，正如你现在看到顶部的那样；
• 显示＜ 章节名称、章节名称 ＞的标题，点击进行章节间跳转；

- 注意 -编写 Markdown 文档时，须在封面后添加标签[TOC]。

逐段浏览模式

• 在进行文档评审或演示时，可以通过激活逐段浏览模式，对单块内容进行识别和聚焦；

• 可通过鼠标双击文档任意内容激活该模式，也直接通过快捷键激活（致敬 VI / VIM 的 JKHL）：

  快捷键	功能
  J	下一个内容块
  K	上一个内容块
  H	往前十个内容块
  L	往后十个内容块

文档插图浏览器

• 支持图片、图表格式：

  • 浏览器支持的所有图片（jpg / png / gif / bmp / ..）
  • 脚本化图表（mermaid³，从V9开始移除对 flowchart.js⁴、JS Sequence Diagrams⁵的支持）

• 点击任意图片、图表打开插图浏览器进行查看；

• 支持在新标签打开图片、图表；

• 支持按前一张、后一张方式浏览文档中的所有插图；

• 对于缺失的图片以默认图片进行替换显示；

• 点击插图能直接跳转到文档中对应的位置，支持通过热键/快捷键esc关闭插图浏览器；

这是普通的图片示例

演示辅助

聚光灯模式

• 在进行文档评审或演示时，可以通过激活聚光灯来让观众聚焦于文档的特定区域和内容；
• 通过双击文档任意位置进行激活或关闭聚光灯。

表格十字光标

• 对导出的 HTML 文件，鼠标悬停在单元格时自动高亮对应的表格整行、整列，便于在大表格时查看相关行列信息；
• 查看示例效果

内容互动

在新标签打开插图、表格、代码块

• 支持在新标签打开文档中的插图、表格、代码块，便于在长文档、多个内容间进行切换、对比浏览；
• 鼠标悬念在插图、表格时，在左上角显示「在新标签打开」的按钮；
• 在新标签中打开的页面，同样支持部分 VLOOK 的特性，如：聚光灯模式、表格十字光标、代码块一键复制等；
• 查看示例效果。

- 注意 -该特性须导出 HTML 并注入 VLOOK 插件后才能生效。

代码块增强

• 更实用、更美观的代码块样式，支持 Dark 模式；
• 支持高亮当前行、一键复制代码；

- 注意 -须先启用显示代码行号配置。启用方式：「Typora → 偏好设置 → Markdown → 代码块 - 显示行号」

![应用 VLOOK 后的代码块示例]

xxxxxxxxxx
18
1
void quickSort(int arr[], int left, int right) {
2
      int i = left, j = right, tmp, pivot = arr[(left + right) / 2];
3
      /* partition */
4
      while (i <= j) {
5
            while (arr[i] < pivot) i++;
6
            while (arr[j] > pivot) j--;
7
            if (i <= j) {
8
                  tmp = arr[i];
9
                  arr[i] = arr[j];
10
                  arr[j] = tmp;
11
                  i++;
12
                  j--;
13
            }
14
      };
15
      /* recursion */
16
      if (left < j) quickSort(arr, left, j);
17
      if (i < right) quickSort(arr, i, right);
18
}

折叠引用内容

1. 对于「引用」，支持动态折叠操作；
2. 在编辑时可指定默认的折叠状态（收起\展开），这个属于 VLOOK 对 Markdown 语法扩展；
3. 举例如下：

[+] 这里是引用的折叠标题

1. 标题前加[+]<空格>或[-]<空格>；
2. [+]指默认为「收起」状态；
3. [-]指默认为「展开」状态。

[+] 支持多级引用的折叠

这里是多级引用折叠的内容

这是多级引用不提供折叠的内容

[-] 这是默认展开的「引用」

展示的引用的内容

文档内容检查

自动识别缺失的图片

识别出无法加载的图片，并替换为图片缺失提示图，示例如下：

页内链接检查

• 自动检查页面内部链接的正确性；
• 若存在无效的页内链接，则通过弹窗提示。

重名章节标题检查

• 自动检查文档是否存在重名的标题，以提示作者检查是否会存在页内链接不能跳转到重名的标题位置的可能性；
• 重名章节标题的警告提示信息须启动浏览器的开发者工具或调试工具后，打开其控制台窗口进行查看。

外部链接强制在新标签打开

为提高文档阅读与交互体验，对于外链（如：http、https、ftp等），自动强制设置为在新标签页中打开。

视觉与交互

Dark 模式

根据浏览器的配置，自动适配 Light / Dark 模式，也支持手动方式进行切换。

支持对指定图片在 Dark 模式时用反色显示

• 图片默认在 Dark 模式时按原始颜色显示，对于一些透明底的 PNG 图片（如界面线框图），可指定在 Dark 模式时以反色显示以获得更好的显示效果；
• 对不起要在在 Dark 模式中以反色显示的图片，可在图片地址末尾增加反色标识?invert=in-dark；
• 举例： ![题注](xxxxx.jpg?invert=in-dark)

多字体样式

• 目前支持 衬线 与 非衬线 两套字体样式，可根据个人喜好进行切换，后续将会有更多见风格加入；

• 衬线与非衬线分别优先使用开源的 思源黑体 和 思源宋体，建议下载安装获得更好的视觉体验；

• 下载字体：

  • 思源黑体 / Noto Sans（常规体、粗体）
  • 思源宋体 / Noto Serif（常规体、粗体）

更友好的脚注查看方式

• 默认情况下，查看脚注信息须在文档中来回跳转；
• 增强后的脚注功能可以直接在当前页面位置全屏显示；
• 点击文末的脚注编号查看脚注信息⁶

更美观的公式

行内公式

$\lim_{x \to \infty} \exp{-x}=0$

多行公式

打印样式适配

• 打印输出时自动优化页面显示样式，以适应用打印输出的应用场景。

快捷键操作

![全局快捷键]

![插图浏览器快捷键]"注：打开插图浏览器后生效"

![聚光灯快捷键]"注：打开聚光灯后生效"

打赏

若喜欢 VLOOK™ 的话，可以请 Max 喝杯咖啡～

如何使用

第1步：下载、配置

• 访问 VLOOK 官方主页下载最新发布版本：https://github.com/MadMaxChow/VLOOK/releases

• 下载并安装 Typora ，启动后进入「偏好设置」，启用一些建议的选项，详细如下图：

   

  

第2步：应用主题

• 将released\theme下所有CSS文件复制至 Typora 的主题目录（ Typora「偏好设置」中点击「外观 - 打开主题目录」定位到该目录）；
• 重启 Typora ，点击菜单主题，选择以vlook-*形式命名的主题，即可启用对应的 VLOOK 主题样式；
• 可基于VLOOK\3-demo\VLOOK-Template 文档模板.md来创建你自己的文档，VLOOK\3-demo目录下也有本文档的 Markdown 源文件。

第3步：植入插件

• 在 Typora 中将 Markdown 文件导出为HTML文件；

• 打开文件released\VLOOK-TOOLBOX 插件.txt，全选所有内容，并复制；

• 用纯文件编辑器，如：记事本、Visual Studio Code，打开该导出的 HTML 文件；

• 搜索「<body 」，并将复制的内容粘贴到body标签的「>」之后：

  xxxxxxxxxx
  4
  1
  <body ...>
  2
  ← ← ← ← ← 复制的「VLOOK-TOOLBOX 插件」内容粘贴于此！
  3
  ...
  4
  </body>
  

• 保存，大吉大利。

强烈建议使用 Chrome 或 Firefox 浏览器查看

许可协议

MIT许可证

版权所有 (c) 2018 MAX°DESIGN | Max Chow 在此授予任何获得此软件和相关文档文件（“软件”）副本的人免费许可，以无限制地处理本软件，包括但不限于使用，复制，修改，合并，发布，分发，再授权和/或出售本软件的副本，并允许本软件的授予人员遵从以下情况： 上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。 本软件按“原样”提供，不提供任何以表达或暗示，包括但不限于销售，适用于特定用途和不侵权的保证。在任何情况下，作者或版权所有人不对因软件或软件的使用或其他事宜产生的任何索赔，损害或其他责任（无论是在合同，侵权或其他方面的诉讼中）负责。

######