VLOOK快速参考手册


VLOOK™
让你的 Markdown 有了新看法
──
快速参考手册
#最新版本|V9.23#idle

MΛX°孟兆
COPYRIGHT © 2016-2020. MAX°DESIGN.

[TOC]

VLOOK™ 是什么

#最新版本|V9.23#msg #适用编辑器|Typora#notice #开源协议|MIT# #开发语言|JavaScript/HTML/CSS#spare #官网|https://github.com/madmaxchow/VLOOK#tips

VLOOK™ 是针对由 Typora[^Typora](目前最好的跨平台 Markdown 编辑器,没有之一)导出的 HTML 文件进行增强的插件。

VLOOK™ 也许是目前最好的 Markdown 增强插件之一,也是==开源中国(OSChina.net)推荐的国产开源产品==。

VLOOK™ 属于开源软件,遵从 **MIT 许可证**。

[+] VLOOK™ 许可协议

MIT许可证

版权所有 (c) 2018-2020 MAX°DESIGN | Max Chow

在此授予任何获得此软件和相关文档文件(“软件”)副本的人免费许可,以无限制地处理本软件,包括但不限于使用,复制,修改,合并,发布,分发,再授权和/或出售本软件的副本,并允许本软件的授予人员遵从以下情况:

上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。

本软件按“原样”提供,不提供任何以表达或暗示,包括但不限于销售,适用于特定用途和不侵权的保证。在任何情况下,作者或版权所有人不对因软件或软件的使用或其他事宜产生的任何索赔,损害或其他责任(无论是在合同,侵权或其他方面的诉讼中)负责。

[+] Markdown 是什么?

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

[+] 60 秒学会、10 分钟深入学习 Markdown 语法:

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

[^Typora]: Typora 是非常棒的跨平台的 Markdown 编辑器,支持直接预览与编辑,更详细的特性详见官网

适用场景

如果你也有以下一个或多个需求或痛点,就可以放心地尝试基于 Markdown 的解决方案(如 Typora + VLOOK)进行文档的编辑、发布、管理:

  • 团队或项目的文档须==统一模板与输出==,并能随时切换不同模板
  • 只关注文档内容的撰写,==排版==这种工作希望能==自动化==完成
  • ==以网络作为主要的发布渠道==,主要发布为 HTML 格式,同时能发布为 PDF 等其它常用格式
  • ==减少==在文档(如 Word)、制图(如 Visio)等软件工具方面的==购买支出==
  • 需要支持==跨平台==(Windows / macOS / Linux 等)进行文档的编辑的与输出的软件工具
  • 文档排版、交互、个性化主题等功能方面,具备可持续升级的能力和开放性

特性清单

VLOOK™ 充分挖掘和扩展了 Markdown 和 Typora 的语法和功能,并结合现代网络化的文档编辑和出版中涉及的文档的 格式排版文档导航演示辅助内容交互 等方面的需求,为你提供基于 Markdown 的文档编辑、文档发布、文档阅读者提供 一致简洁友好 的体验。

#提示#tips 你正在浏览在这个网页就是由 Typora 编辑并植入 VLOOK™ 插件所生成,并应用了 VLOOK™ 的所有的特性

![VLOOK™ 特性清单]”环境要求:VLOOK™ V9.7+,Typora mac版 V0.9.9.31+ / Win版 V0.9.83+”
VLOOK™ 的特性及简介
==一、排版增强==
封面、封底
配合主题样式,让你用 Markdown 写的文档也能焕发专业气质
多主题样式
让你的文档尽显个性,同时提供主题定制服务
标题、插图、表格、表格行支持自动编号
“0”配置,跟 Word 说 ByeBye 吧~
自动生成插图、表格、代码块、音/视频的题注
OMG!配合插图、表格、代码块、音/视频的自动编号,高效高颜值!还有独特的双题注~
表格单元格合并
这个是用 Markdown 人的真痛点,在这时为你提供了优雅的解决方法
表格列格式化
Markdown 的表格也能快速设置列的格式(如加粗、高亮、斜体、下划线),同样为你提供了优雅的解决方法
彩虹标签
可自定义多个配色的标签、双标签,让你的 Markdown 文档排版更专业、更标准化
[mermaid 样式优化](#mermaid 样式优化)
全面深度优化 mermaid 图表,并提供补丁修正其跨平台的兼容性问题
图片反色、增加边缘空白
可指定在 Dark 模式时反色,还能增加边缘空白,让图片的呈现更和谐、阅读体验更佳
统一多级列表自动编号
将多级有序、无序列表的编号进行了统一,以更聚焦内容的结构化
任务列表支持自动编号
让任务列表和多级列表的自动编号两者兼得
==二、文档导航==
大纲导航
最为熟悉和常用的文档导航方式,支持多级章节折叠
(适合于全局快速定位到文档内的目标章节)
逐章导航
在长文档中特别好用,随时眯一眼就知道当前章节、前 / 后章节是什么了
(适合于在多章节间频繁切换,浏览相近章节的内容)
逐段导航
这个很 GEEK,可以通过键盘逐段进行浏览,习惯用 VI / VIM 的人应该会欢呼!
(适合于内容审核、讲解时,让演讲人与观众共同聚焦到同一段上)
插图导航
让你快速在快速浏览文档的所有插图,并能直接跳到文档中对应的位置
==三、演示辅助==
聚光灯
太COOL了!在投影时可以让大家快速聚焦在关键内容上了
表格十字光标
方便你与大家讨论长表格、大表格时,快速聚焦指定单元格,及对应的行和列
在新标签打开插图、表格、代码块
在长文档中的来回翻页查看插图、表格、代码示例是很崩溃的事,现在你可以让它们在浏览器的不同标签中显示了
==四、内容互动==
表格行分组
程序员、产品经理呼声最高的表格增强之一,从此你的表格就可以轻松实现分组和多级缩进了
支持音频、视频
你的 Markdown 文档从此可以看视频、听音频了,音频还支持迷你模式,应用的潜力等你来发挥~
代码块增强
在这你会发现连闷骚的代码都透着动感,高亮当行、复制~
引用内容可设置为折叠
引用内容很长很多?现在可以指定是否默认收起,读者点击才展示引用内容……在 VLOOK™ 的加持下,这里都不是事
长内容自动折叠
长图、长表格、长代码会占用太多屏幕空间?现在可以统统自动折叠,静待你的二维展开指令
文档内容检查与优化
文档中的页内链接、图片链接失效了,现在 VLOOK™ 会悄悄告诉你的
更友好的脚注
用 Markdown 也可以像 Kindle 那样以弹窗方式来看脚注
==五、视觉与交互==
[Dark 模式](#Dark 模式)
这个不用多说了,懂的人都会喜欢。也可手动切换回标准的 Light 模式
字体风格选择
AMAZING! 不同的字体风格为你的文档带来不同的调性~
更美观的公式
让你的各种公式长得与 VLOOK™ 的不同主题更搭
打印样式适配
使用 VLOOK™ 提供的打印功能,确保文档样式适合商务办公场景下的打印输出
快捷键操作
支持键盘快捷键操作,又可以再装个逼了~
跨平台支持
能自适应在 PC 、平板、手机上进行浏览
自动识别链接类型
自动识别对文档的内部链接、外部链接,鼠标在链接上悬停时通过不同的角标图示进行区分
七语种界面
界面提示说明、题注前缀等内容,均支持:简/繁/英/法/俄/日/韩(依赖于浏览器的当前语言设置)

特性介绍

排版增强

有了 VLOOK™ 主题及插件的支持,让你对 Markdown 编辑器(暂只支持 Typora)的自动化排版能力有了全新的理解。

多主题样式

VLOOK™ 已为你内置了多套原创、独具风格的主题样式[^主题样式],能满足日常大多不同的应用场景和视觉偏好:

内置高颜值实用的主题

[+] 我要怎样才能使用这些内置的主题?

下载并添加主题文件(vlook-*.css)到 Typora 主题目录后,在导出 HTML 前通过 Typora 的「主题」菜单选择以「VLOOK」为前缀的主题,如:Vlook hope

── 更多使用指引详见《如何使用

#私人定制#目前 VLOOK™ 项目也现已开放了主题的 私人定制 服务 #微信|MaxChow#tips,定制样品示例如下:

私人定制主题

[^主题样式]: 可以根据源码目录下 LESS 文件为样例进行自定义扩展,访问 VLOOK™ 的 github 主页了解更多。

封面、封底

应用了 VLOOK™ 的主题后,即可通过 Markdown 的标准语法(须按 VLOOK™ 约定的使用规范)即可激活对应主题的封面、封底。

[+] 这样就能激活封面!

在文档的最开始输入一个 6 级标题###### 这是封面标题即可激活,同时已内置对特定类型信息的自动排版,具体如下:

[+] 标题

  • 默认格式就是标题格式,直接输入就可以了;
  • 可结合 HTML 的上标、下标方式进行大标题、小标题的延伸应用:
    • 上标:<sup>上标内容</sup>
    • 下标:<sub>下标内容</sub>

[+] 文档类型、密级

可使用 VLOOK™ 的双标签风格写法来实现,举例:

  • `#文档密级|对外公开#tips`
  • `#文档密级|内部公开#notice`
  • `#文档密级|机密资料#caution`

[+] 作者

使用 Markdown 的「粗体」格式标记出「作者信息」即可(会自动添加前缀「by」、加粗),举例:**我是作者**

[+] 版权信息

使用 Markdown 的「斜体」格式标记出「版权信息」即可(会自动缩小字号、加粗),举例:*(C)2020. 版权所有*

以下是本文档封面的完整 Markdown 语法示例内容:

###### <sup>VLOOK™</sup><br>让你的 Markdown 有了新看法<br>──<br><sub>快速参考手册</sub><br><br><br><br>**MAX丨孟兆**<br>*COPYRIGHT © 2016-2020. MAX°DESIGN.*

#提示#tips 封面内如何换行? 可直接输入 HTML 的换行标签<br>即可,或直接使用快捷键 Shift + ENTER ↵

[+] 这样就能激活封底!

在文档的最末处输入一个 6 级标题###### 这是封底结语即可激活,同时已内置对特定类型信息的自动排版。

以下是本文档封底的完整 Markdown 语法示例内容:

###### The End

~ SO EASY!

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

如果你使用过 Word 的标题、图表的自动编码功能,就会惊喜地发现,基于 Markdown 也能做到,甚至能做得更好~
既不需要进行额外的设置和语法支持,甚至还能对表格行进行自动行号编号,一起来看看吧。

[+] 标题自动编号

所有 VLOOK™ 的主题都会自动对 1 ~ 5级 标题进行自动编号;

编号的格式就是你在本文各级章节标题所看到的那样;

因为6级 标题在 VLOOK™ 中应用于封面和封底、段落小标题的排版等,所以不在自动编号范围内。

[+] 插图自动编号

支持对文档内所有的插图,包括图片、mermaid 图表进行统一的自动编号,编号格式为:图 XX

正如你在前面看到的那些介绍内置主题的图片那样。

[+] 表格、表格行自动编号

支持对文档内所有表格进行统一的自动编号,编号格式为:表 XX

要激活表格行的自动编号,须在表格前添加任意层级的标题,或为有序 / 无序列表下的缩进表格,如:###### 这是一个表格

表格前添加 6 级标题会激活表格行的自动编号,效果如下
列1列2列3列4
第一行左对齐(长内容)居中对齐右对齐(长内容)
第二行(长内容)左对齐居中对齐(长内容)右对齐
  • 有序 / 无序列表下的缩进表格,会激活表格行的自动编号,效果如下:

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

#提示#tips听说你还想给插图、表格添加题注?好消息是 VLOOK™ 也支持,接着看就能又甩你一个新技能~

自动生成插图、表格、代码块、音/视频的题注

你只需要按 GFM 添加图片的 Markdown 语法,VLOOK™ 就会自动为你的图片添加图注。
如果你要为表格、mermaid 图表,甚至还要同时支持两个题注,这些都可以使用 VLOOK™ 扩展的类似添加图片的语法就能轻松实现~

[+] 这样做,你就能为图片自动生成题注

以 GFM 添加图片的 Markdown 语法为基础:![图片标题](图片URL "可选子标题")

  • 图片标题:即为默认题注,如:![这是图片的默认题注](图片URL)
  • 可选子标题:若填写了可选子标题,该可选子标题就会自动生成为第 2 题注,如:![这是图片的默认题注](这是图片的第2题注)

#注意#以上语法中的「可选子标题」与「图片URL」间须以英文空格 SPACE 进行分隔

[+] 这样做,也能为表格、mermaid 图表、代码块添加题注

  • 懒人方案:
    • 在表格、mermaid 图表、代码块前直接编写题注内容;
    • 然后将内容设置为六级标题(例如:###### 这条是表格题注),同时该六级标题内容在生成题注后,不会被隐藏。
  • 扩展语法、双题注方案:
    • 在表格、mermaid 图表、代码块前增加题注描述,使用语法是 VLOOK™ 扩展 GFM 的添加图片的 Markdown 语法;
    • 语法:``![默认题注]”第2题注”`,其中的「第 2 题注」内容为可选;
    • 该语法的所有内容由 VLOOK™ 转换后被隐藏,若要保留原始标题内容,可另起一行进行描述。

有关 表格、mermaid 图表 的题注效果效果可以继续看下面表格单元格合并的表格样例

表格单元格合并

表格是文档中最多见的元素,虽然 GFM 扩展了 Markdown 的语法实现了对表格的支持,但对排版上的支持还是比较弱。
目前 Markdown 粉们呼声最多的就是单元格合并了~

现在 VLOOK™ 已为你带了简洁、优雅的单元格跨行、跨列合并的解决方案:

[+] 跨列合并(横向)语法

单元格内容为两个连续的左侧尖括号<<进行标识,该单元格将会与左邻的单元格进行合并,以此类推。

#注意#旧语法为两个连续的英文句号==,目前已废弃,不建议使用!

[+] 跨行合并(纵向)语法

单元格内容为两个连续的次方符号^^进行标识,该单元格将会与上方的单元格进行合并,同时还支持表头的跨行合并。

#注意#旧语法为两个连续的英文句号..,目前已废弃,不建议使用!

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

| 普通列头 | #标签|测试#列合并(2列) | << | 普通列头 | 列合并(3列) | << | << |
| —————– | ————————– | ———————– | ———- | ————- | ———- | —————— |
| 行合并(3行) | 普通单元格 | 普通单元格 | 普通单元格 | 普通单元格 | 普通单元格 | 跨行(全合并) |
| ^^ | 行合并(2行)#标签|测试# | 列合并(4列) | << | << | << | ^^ |
| ^^ | ^^ | 普通单元格 | 普通单元格 | 普通单元格 | 普通单元格 | ^^ |
| 普通单元格 | 行合并(3行) | 普通单元格 | 普通单元格 | 普通单元格 | 普通单元格 | ^^ |
| 普通单元格 | ^^ | #标签|测试#普通单元格 | 普通单元格 | 普通单元格 | 普通单元格 | ^^ |
| 普通单元格 | ^^ | 普通单元格 | 普通单元格 | 普通单元格 | 普通单元格 | ^^ |

示例二:表头跨行合并1
列头行合并(2行)列头列合并(2列)<<列头行合并(2行)列头列合并(3列)<<<<
^^二级列头二级列头^^二级列头二级列头二级列头
普通单元格普通单元格普通单元格普通单元格普通单元格普通单元格普通单元格
普通单元格普通单元格普通单元格普通单元格普通单元格普通单元格普通单元格
示例三:表头跨行合并2
列头行合并(3行)列头行合并(3行)列头列合并(3列)<<<<普通列头普通列头
^^^^二级列头1二级列头2二级列头3^^^^
^^^^三级列头1三级列头2三级列头3^^^^
普通单元格普通单元格普通单元格普通单元格普通单元格普通单元格普通单元格

#注意#如果你还需要对表格的列格式进行设置(如整列加粗、斜体等),VLOOK™ 也提供了同样好的支持,详见以下的表格列格式化

表格列格式化

表格是文档中最多见的元素,虽然 GFM 扩展了 Markdown 的语法实现了对表格的支持,但对排版上的支持还是比较弱。

VLOOK™ 除了为你带来单元格合并的能力外,还支持设置表格整列格式的能力~

表格列普通格式化

只须在表头按以标准的 Markdown 或 GFM 的格式设置语法设置对应的格式即可实现整列格式化。

目前支持的格式设置语法:**加粗***斜体*~~删除线~~==高亮==<u>下划线</u>

表格列普通格式化示例
加粗#标签#斜体下划线==高亮==删除线
单元格单元格单元格单元格#标签#单元格单元格`#标签组
单元格单元格单元格单元格内有加粗内容单元格内有加粗内容
单元格单元格单元格单元格内有行内代码内容单元格内有行内代码内容
表格列普通格式化(嵌套)示例
==高亮+下划线==加粗+斜体+下划线==加粗+高亮==删除线+加粗列
单元格单元格单元格#标签#单元格单元格`#标签组
单元格单元格单元格内有加粗内容单元格内有加粗内容
单元格单元格单元格内有行内代码内容单元格内有行内代码内容

表格列增强格式化

通过对列头以 GFM 标准语法为基础进行扩展,以及对不同的对齐方式进行约定处理,以实现对整列的格式。

  • 带复选框的列:表格列关的内容以[(空格)](空格)开头默认该列单元格内容前增加复选框,样式说明如下:

    • 默认为「未选择」样式;
    • 若内容以[x]开头时,为「已选择」样式;
    • 若内容前添加[-]开头时,为「不确定选择」样式。
    复选框样式[ ] 带复选框的列说明
    未选择默认样式
    已选择[x]
    不确定选择[-]
    当值 ≥ 0 时
  • 数值格式列:表格列设置为「右对齐」,则针对数字内容强制设置为「数值」格式,数值格式说明如下:

    • 分隔符:千位符

    • 负数:变色

    • 字体:等宽字体

    • 小数:位数不调整

    数值列(非右对齐)数值列(右对齐)
    123123
    1234-1234
    123456789.00123456789.00
    1234567^.89^1234567^.89^

彩虹标签

VLOOK™ 基于 Markdown 的行内代码标记` ` ,扩展语法来支持 标签(tag) 功能,并能同时支持 单标签双标签(嵌套标签)

单标签风格

  • 语法:

    • 使用行内代码语法``
    • 内容以#开始,并以#结束,如:`#标签#`
  • 支持通过在结束的#后添加指定不同的类型后缀标识(不指定时默认为 caution),实现不同类型的标签会以不同的样式进行渲染:

    ![单标签示例]”(不指定时默认为 caution)”

    后缀标识举例应用场景建议色调渲染效果
    msg`#标签#msg`信息、资讯、公告#标签#msg
    tips`#标签#tips`提示、备忘、参考、新增绿#标签#tips
    notice`#标签#notice`提醒、注意、关注、优化、修复#标签#notice
    caution`#标签#caution`警告、危险、关键事项、删除#标签#caution
    spare`#标签#spare`延伸、扩展、保留、备用#标签#spare
    idle`#标签#idle`无效、暂缓、停用、结束#标签#idle

双标签风格

  • 支持嵌套式的双标签,满足二元结构内容的应用需要,举例如下:

    • #版本号|V1.0.2#msg
    • #变更 X 的取值|1234.00#tips
    • #优先级|中#notice
    • #优先级|高#
  • 语法:在「单标签」语法的基础上,以英文竖线符号|作为分隔符,如`#标签组|标签#`

    ![双标签(嵌套标签)示例]”(不指定时默认为 caution)”

    后缀标识举例应用场景建议色调渲染效果
    msg`` `#标签组标签#msg` ``信息、资讯、公告
    tips`` `#标签组标签#tips` ``提示、备忘、参考、新增绿
    notice`` `#标签组标签#notice` ``提醒、注意、关注、优化、修复
    caution`` `#标签组标签#caution` ``警告、危险、关键事项、删除
    spare`` `#标签组标签#spare` ``延伸、扩展、保留、备用
    idle`` `#标签组标签#idle` ``无效、暂缓、停用、结束

mermaid 样式优化

VLOOK™ 针对比较受关注的 mermaid 图表提供了样式的统一和优化,并提供跨平台跨浏览器的兼容性补丁。

[+] 统一和优化样式

支持 mermaid 的 饼图、流程图、状态图、顺序图、类图、甘特图,同时还能自动适配 [Dark 模式](#Dark 模式)。

除了样式优化外,还对书写规范进行了统一,效果比其官网的要好上许多许多~

  • 基于流程图衍生出状态机图;
  • 针对顺序图,支持不同角色类型(人、系统、重要系统、外部系统),重绘不同的外观样式;
  • 针对顺序图的 #opt#spare #alt / else# #loop#notice 标签优化不同的外观样式,以及自动翻译为当前浏览器的语言。

[+] 跨平台跨浏览器的兼容性补丁

操作系统涉及 Windows、macOS、Linux,分辨率涉及到普通和高清,浏览器涉及主流的 Chrome / Firefox / Edge。

mermaid 的图表在以上复杂情况下的一致性还是做得不够到位,所以 VLOOK™ 提供了一个非官方的兼容补丁,为大家提供一个更好的浏览体验

mermaid 的流程图

![流程图]”(以上的「分支流程」内容由下图进行接续)”

graph LR
START(开始) --> node1(普通节点)
subgraph 子图
	node1 --> |情况1|groud1[流程组节点]
  node1 --> |情况2|A1((A))
end

%% this is a comment

groud1 ==> |重要分支|cond1{条件判断}
cond1 --> |是|END
cond1 -.-> |否|page2>分支流程]
A2((A)) --> END
END(结束)

![分支流程(接续上图)]

graph LR
page2>分支流程] --> node2(普通节点)
node2 --> END
END(结束)
mermaid 的状态图

![由 mermaid 流程图语法衍生的状态图]

graph LR
%% 流程图走方说明
%% LR:从左到图,RL:从右到左,TB:从上到下,BT:从下到上

INIT(( )) -->	|初始|A[状态A]
A --> |复杂变更|fork1(( ))
fork1(( )) --> |变更条件说明|B[状态B]
B --> |变更条件说明|C[状态C]
fork1{ } -.-> |非正常/次要变更条件说明|C
C --> FINAL
fork1{ } -.-> |非正常/次要变更条件说明|D[状态D]
D --> FINAL
FINAL(( ))
mermaid 的顺序图

![多种不同角色的顺序图,更清晰、更友好]

sequenceDiagram
%% 设置显示消息的自动编号
autonumber

participant User as @人物角色
participant Client as 系统角色
participant Server as **重要系统角色**
participant Extend as --外部系统角色--

par 平行消息
	User ->> Client: 平行发送消息1
and
	User ->> Client: 平行发送消息2
and
  Client ->>+ Server: 平行发送消息3
  Server -->>- Client: 发送消息
end

%% 设置区域高亮
rect rgba(128, 128, 128, 0.3)
	Extend ->> Extend: 内部动作
end

Note left of Extend: 显示在外部系统<br>左侧备注说明
Note right of Extend: 显示在外部系统<br>右侧备注说明
Note over Client,Server: 跨对象备注说明
loop 循环
	Client ->>+ Extend: 发送消息A
	alt 抉择1
		Server -->> Client: 同步返回消息A1
	else 抉择2
		Server --X Client: 异步返回消息A2
	end
	opt 可选
		Extend ->>- Server: 发送消息X
	end
end

#参考#tips更多脚本化图表样式,以及结合 VLOOK™ 相关的脚本编写规范内容详见《脚本化图表 for Markdown》。

图片反色、增加边缘空白

应用了 VLOOK™ 主题的文档,针对图片提供了更加精细的排版特性。

指定图片在 Dark 模式时反色显示
  • 图片默认在 Dark 模式时按原始颜色显示,对于一些透明底的 PNG 图片(如界面线框图),可指定在 Dark 模式时以反色显示以获得更好的显示效果;
  • 对需要在 Dark 模式中以反色显示的图片,可在图片 URL 增加启用 Dark 模式反色标记invert=in-dark,举例如下:

图片默认样式(不指定在 Dark 模式时反色)

指定切换至 Dark 模式后反色后会长这样(指定了在 Dark 模式时反色)

指定图片添加边缘空白
  • 对需要添加边缘空白的图片,可在图片 URL 增加启用边缘空白的参数padding=true
  • 举例: ![图片题注](xxxxx.png?padding=true)
  • 以上两图图片已开启边缘空白,以适合图片内容过于贴边,无留白的情况。

[+] 图片 URL 参数语法说明

  • 图片 URL 无参数时:先在 URL 后添加英文问号?后,再添加需要的 URL 参数: ![图片题注](xxxxx.png?invert=in-dark)
  • 图片 URL 已有参数时:多个参数间用英文特殊符号&进行分隔: ![图片题注](xxxxx.png?invert=in-dark&padding=true)

统一多级列表编号

对所有有序无序的多级列表编号进行了统一以有序编号为主,无序编号为辅,简化多级内容的编写。

[+] 列表分级编号样式效果

  • 一级列表内容

  • 一级列表内容

    • 二级列表内容
      • 三级列表内容
        • 四级列表内容
          • 五级列表内容
            • 六级列表内容
  • 三级列表内容

Markdown 原始内容参考如下:

- 一级列表内容
   - 二级列表内容
     - 三级列表内容
       - 四级列表内容
         - 五级列表内容
           - 六级列表内容
1. 一级列表内容
   + 二级列表内容
     - 三级列表内容

任务列表支持自动编号

GFM 标准的任务列表(to-do)默认会取消其列表编号。
VLOOK™ 主题会保持任务列表特性基础上,恢复列表编号的显示,并与上面统一多级列表编号保持一致。

举例如下:

  • 这是一级任务列表项
    • 这是二级任务列表项
    • 这是「已完成」的二级任务列表项
      • 这是三级任务列表项
        • 这是四级任务列表项
          • 这是五级任务列表项
            • 这是六级任务列表项
    • 这是二级任务列表项
  • 这是一级任务列表项

文档导航

VLOOK™ 提供了对文档章节、插图提供了多种形式的导航和快速定位的工具,全面改善和提高发布的 HTML 文件的浏览体验和效率。
敬请你根据需要和喜好随时、轻松享用~

![文档导航工具及适用场景]

导航工具适用场景
大纲导航适用于目标明确,跨多个章节的快速定位
逐章导航适用于前后章节相关度高,按章节顺序一章一章进行浏览
逐段导航适用于文档评审或演示,按段落一段一段进行聚焦式浏览
插图导航适用于按图索骥,通过浏览文档中的插图(图片、mermaid 图表)来直接跳到文档中对应的位置

大纲导航

在封面时,点击左上角的大纲按钮打开大纲导航面板。不在封面时,会自动贴在文档左侧固定显示大纲导航面板。
支持对章节进行折叠 / 展开。

#注意#编写 Markdown 文档时,须在封面后添加目录标记[TOC]才能在导出的 HTML 中生成大纲面板。

逐章导航

进入文档正文区后,会自动在顶部显示逐章导航条,在封面时会自动收起隐藏,支持对 1~5 级章节进行逐章浏览。
从左到右分别为:前一章节当前章节后一章节,正如你现在看到顶部的导航栏那样。
鼠标点击对应的章节直接跳转到对应的章节开始位置,也可通过左 / 右方向键进行操作。

#注意#编写 Markdown 文档时,须在封面后添加目录标记[TOC]才能在导出的 HTML 中生成逐章导航面板。

逐段导航

在进行文档评审或演示时,可以激活逐段导航,对单段内容进行聚焦。
通过鼠标双击文档任意段落激活逐段导航模式,并通过快捷键进行上 / 下改变当前聚焦的段落。

![逐段导航的浏览操作方式(致敬 VI / VIM)]

快捷键功能
J下一个段落
K上一个段落
H往前跳十个段落
L往后跳十个段落

插图导航

  • 点击任意插图可直接启动插图导航,或点击工具栏上的插图导航图标启动;
  • 点击插图导航内的插图,能直接跳转到文档中对应的位置。

[^mermaid]: mermaid 是一个用于画流程图、状态图、顺序图、甘特图的库,使用 JS 进行本地渲染,广泛集成于许多 Markdown 编辑器中。详见 mermaid官网,或 VLOOK™ 的示例文档《脚本化图表 for Markdown
[^flowchart.js]: flowchart.js 基于 SVG 的流程图插件,它仅需几行代码即可在 Web 上完成流程图的构建。可以从文字表述中画出简单的 SVG 流程图,也可以画出彩色的图表。详见 flowchart.js 官网,或 VLOOK™ 的示例文档《脚本化图表 for Markdown》。
[^JS Sequence Diagrams]: JS sequence diagrams 是一个方便建立UML的顺序图(序列图or循序图)在线工具,使用简单。详见 JS Sequence Diagrams 官网,或 VLOOK™ 的示例文档《脚本化图表 for Markdown》。

[+] 支持的插图类型

  • 浏览器支持的所有图片(如:jpg / png / gif / bmp 等)
  • 脚本化图表(mermaid[^mermaid],从V9.0开始移除对 flowchart.js[^flowchart.js]、JS Sequence Diagrams[^JS Sequence Diagrams]的支持)
这是长图片示例:

普通的图片示例(长图会自动折叠)

演示辅助

VLOOK™ 独创性地为 Markdown 导出的 HTML 提供了强大的演示辅助工具,让面向 Markdown 的 Typora + VLOOK 成为更具生产力的交互式文档出版工具。

非常适合现场和远程的演示辅助工具,敬请为你的 Markdown 开启 Turbo 模式~

![演示辅助工具及适用场景]

演示辅助工具适用场景
聚光灯对局部内容进行聚焦,如:插图、多个段落内容
表格十字光柱针对表格内容,特别是行 / 列关联性强的表格,快速关联任意单元格的横向、纵向单元格序列
新标签打开插图、表格、代码块针对须频繁在多个插图、表格、代码块间进行切换时使用,大大减少不必要的文档内跳转

聚光灯

在进行文档评审或演示时,可以通过激活聚光灯来让观众聚焦于文档的特定区域和内容。

通过工具栏上的「聚光灯」按钮打开 / 关闭,也可通过快捷键 S 进行操作,同时还可以通过按下 ⇧ Shift 键调节大小。

#小提示#tips聚光灯在新标签打开的页面中也可以使用喔~

表格十字光标

鼠标点击表格上的任意单元格后,会自动显示十字光标,高亮其横向、纵向关联对应的单元格序。

查看示例效果

#小提示#tips表格十字光标在新标签打开的页面中也可以使用喔~

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

支持在新标签中打开文档中的 插图表格代码块,鼠标悬念在这些文档内容上时会在左上角显示「在新标签打开」的按钮,点击即可。

查看示例效果

内容互动

得益于成熟的 Web 浏览器、HTML / CSS、JavaScript 技术,让静态的文档也能与你一起「动」起来。

表格行分组

为满足对于产品设计文档、技术文档(如 API 接口文档)都会在同一个表格内,对不同的表格行进行分组。VLOOK™ 结合了 GFM 的表格和引用的语法,扩展支持对表格行进行分组。

在任意表格行的首列,使用 Markdown 的引用的语法>(空格),即可表示该行缩进一级,其前一行即为上一级的分组;多个>表示缩进多级,如三级缩进>>>(空格)

分级写法举例
一级缩进> 这是一级缩进
二级缩进>> 这是二级缩进
三级缩进>>> 这是三级缩进
(以此类推)<<
表格行分组举例如下:
列头1[ ] 勾选列列头2
普通行
普通行
普通行
[ 分组 1 ]
> 这是属于分组 1 的内容 1.1[x]该行是被折叠的行
> 这是属于分组 1 的内容 1.2该行是被折叠的行
普通行
普通行
[ 分组 2 ]<<<<
> 这是属于分组 2 的内容 2.1[x]该行为被折叠的行
> 这是属于分组 2 的内容 2.2该行为被折叠的行
> [ 这是属于分组 2 的内容 2.3(二级分组)][x]该行为被折叠的行
>> 这是属于二级分组 2.3 的内容 2.3.1该行为被折叠的行
>> [ 这是属于二级分组 2.3 的内容 2.3.2(三级分组)]<<<<
>>> 这是属于三级分组 2.3.2 的内容 2.3.2.1[x]该行为被折叠的行
> 这是属于分组 2 的内容 2.4该行为被折叠的行
普通行[x]单元格内容
普通行
普通行
普通行
普通行
普通行
普通行

支持音频、视频

音频

支持的音频格式:MP3 (.mp3)、Ogg (.ogg)、Wav (.wav)、M4a (.m4a)

语法与 Mardown 的插入图片保持一致(在标准模式控件时可支持自动题注)。
语法:![音频题注](音频URL "音频第2题注"),如:![这是音频](audio.mp3)

音频播放控件默认为:标准模式

音频播放控件默认为标准模式

音频播放控件可指定为:Mini 模式

← 点击播放

![音频内容支持定制的内容]

可定制特性URL 参数示例
启用 Mini 模式的播放控件controls=mini
启用 播放/暂时 模式
(默认为 播放/结束)
pause=true
#注意#仅 Mini 模式下有效
显示音频时长duration=true
#注意#仅 Mini 模式下有效
开启自动播放autoplay=true
开启循环播放loop=true循环播放音频示例
开启预加载preload=true预加载音频示例

[+] 音频 URL 参数语法说明

  • 音频 URL 无参数时:先在 URL 后添加英文问号?后,再添加需要的 URL 参数: ![音频题注](xxxxx.mp3?controls=mini)
  • 音频 URL 已有参数时:多个参数间用英文特殊符号&进行分隔: ![音频题注](xxxxx.ogg?controls=mini&loop=true)

视频

支持的格式:Ogg (.ogv)、MPEG4 (.mp4)、WebM (.webm)

语法与 Mardown 的插入图片保持一致,可支持自动题注
语法:![视频题注](音频URL "视频第2题注"),如:![这是视频](video.webm)

视频示例

![视频内容支持定制的内容]

可定制特性URL 参数示例
开启自动播放autoplay=true
开启循环播放loop=true
开启预加载preload=true预加载视频示例
指定视频宽度width=xxx指定视频的宽度(单位:px)
指定视频高度height=xxx指定视频的高度(单位:px)

#提示#tips视频 URL 参数语法与音频一致

代码块增强

更实用、更美观的代码块样式,支持高亮当前行、一键复制代码,还能自动适配 [Dark 模式](#Dark 模式)。

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

![VLOOK™ 的代码块示例]”语法着色器: C++”

// ================================================== //
//            VLOOK™ 支持对长代码块进行自动折叠           //
// ================================================== //

/**
 * 快速排序
 * @param arr 排序的目标数据
 * @param left 排序范围左值
 * @param right 排序范围右值
 */
void quickSort(int arr[], int left, int right) {
    int i = left, j = right, tmp, pivot = arr[(left + right) / 2];
  
    /* partition */
    while (i <= j) {
        while (arr[i] < pivot)
            i++;
        while (arr[j] > pivot)
            j--;
        if (i <= j) {
            tmp = arr[i];
            arr[i] = arr[j];
            arr[j] = tmp;
            i++;
            j--;
        }
    };

    /* recursion */
    if (left < j)
        quickSort(arr, left, j);

    if (i < right)
        quickSort(arr, i, right);
}

// ================================================== //

引用内容可设置为折叠

对 Markdown 「引用」> 引用内容进行简单的扩展,实现对引用内容的动态的折叠 / 展开操作,还可以设置默认姿势是折叠,还是展开。

举例如下:

[+] 以下是默认折叠的「引用」内容

  • 在作为折叠引子的内容前增加:[+]<空格>[-]<空格>

    • [+]指该标题下的引用内容默认为「收起」状态;
    • [-]指该标题下的引用内容默认为「展开」状态;
  • 然后换行后添加一个新的嵌套的引用块,该嵌套的引用块即为该引子对应要折叠 / 展开的内容。

[+] 可支持多重引用的折叠

[+] 这里是第三重引用折叠的内容

这是第三重引用的内容

[-] 以下是是默认展开的「引用」内容

默认为展示的引用内容

扩展的 Markdown 语法参考如下:

> [+] 我是折叠的引子
> > 我是被折叠的内容
> > 我是被折叠的内容

长内容自动折叠

文档中的长插图、长表格、长代码会占用过多的屏幕空间,通过 VLOOK™ 可以实现对这些长内容的自动折叠;

• 长图片查看示例

• 长的表格查看示例

• 长代码查看示例

文档内容检查与优化

自动识别缺失的图片

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

缺失的图片

页内链接检查

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

重名章节标题检查

自动检查文档是否存在重名的标题,以提示作者检查是否会存在页内链接不能跳转到重名的标题位置的可能性。

#注意#重名章节标题的警告提示信息须启动浏览器的开发者工具或调试工具后,打开其控制台窗口进行查看。

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

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

视觉与交互

人类从来都是视觉动物,自己或他人在阅读时,让眼睛感受愉悦和美好,是一种美德、一种力量、一种信仰。

                                        ── MAX丨孟兆

欢迎屏

默认情况下,文档和插件加载过程中会自动显示欢迎屏,完成加载后,可手动关闭并显示文档。

若希望不显示,或希望在完成加载后自动关闭欢迎屏,可通过添加 URL 参数的方式进行指定,具体说明如下:

URL 参数URL 参数取值说明举例
wsnone不显示欢迎屏你的文档.html==?ws=none==
wsauto文档和插件加载完成后,自动关闭欢迎屏你的文档.html==?ws=auto==

Dark 模式

所有 VLOOK™ 的主题,都会自动根据浏览器的配置,自动适配显示 Light / Dark 模式,也支持手动方式进行切换。

Light / Dark 效果预览

#提示#tips如果你的图片在 Dark 模式下显得不够和谐,可以尝试选择让图片在 Dark 模式时自动反色

字体风格选择

支持 衬线非衬线 两套字体风格,可根据个人喜好进行切换,后续将会引入更多字体风格。

衬线与非衬线分别优先使用开源的 思源黑体思源宋体,建议下载安装获得最佳的视觉体验。

[+] 字体下载地址

更友好的脚注

默认情况下,Typora 导出的 HTML 在查看脚注时会在文档中来回跳转。

通过 VLOOK™ 插件优化后的脚注,可以直接在当前页面位置弹层的方式进行显示,可点击文末右上角的链接查看效果[^脚注1]

[^脚注1]: 这是 VLOOK™ 优化后的脚的信息

更美观的公式

行内公式

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

多行公式

$$
\mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix}
\mathbf{i} & \mathbf{j} & \mathbf{k} \
\frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \
\frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \
\end{vmatrix}
$$

打印样式适配

使用 VLOOK™ 提供的定制打印功能,可以在打印输出时自动优化页面排版和样式,以适应用打印输出。

快捷键操作

![全局快捷键]

快捷键功能
D开启 / 关闭 Dark 模式
O显示 / 隐藏大纲面板
A切换字体样式,详见字体风格选择
I显示 / 隐藏插图导航
P打印文档
S打开 / 关闭聚光灯
上一章
下一章
JKHL内容块浏览操作,详见逐段导航
ESC关闭弹出的界面、聚光灯、内容块聚焦等

![插图导航快捷键]”注:打开插图导航后生效”

快捷键功能
前一张插图
后一张插图

![聚光灯快捷键]”注:打开聚光灯后生效”

快捷键功能
⇧ Shift调整聚光灯大小

打赏

若喜欢 VLOOK™ 的话,可以请 MAX 喝杯咖啡~

a cup of MAX˚coffee

如何使用

第1步:下载、配置

  • 访问 VLOOK™ 在 GitHubGitee 的主页下载最新发布的版本;
  • 下载并安装 Typora ,启动后进入「偏好设置」,并开启以下选项,详见下图:

开启「Markdown ▸ 代码块、公式」下的所有选项

开启「Markdown ▸ Markdown 扩展语法」下的所有选项

第2步:应用主题

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

第3步:植入插件

  • 在 Typora 中将 Markdown 文件导出为HTML文件;
  • 打开文件released\VLOOK-plugin-for-Typora.txt,全选所有内容,并复制;
  • 用纯文件编辑器,如:记事本、Visual Studio Code,打开该导出的 HTML 文件;
  • 搜索「**<body **」,并将复制的内容粘贴到 body 标签的关闭符「**>**」之后:
    <body ...>
    ◀ ◀ ◀ 将「VLOOK-plugin-for-Typora.txt」文件的内容粘贴于此!
    ...
    </body>
  • 保存,大吉大利。

强烈建议使用 Chrome、Firefox、Edge 浏览器访问

The End

文章作者: 古客
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 古客 !
评论
  目录