经常使用markdown 的玩家一定很想要一个自动生成的导航栏吧,自己写的基本思路就是
轮询监听滚动条的位置,通过抛锚和跳锚实现,这里介绍一下今天的主角,markdown-toc插件:
https://github.com/jonschlinkert/markdown-toc
# 0x00 安装
TOC = Table of content , 将内容制作成导航
这个插件是基于 nodejs 的,因此需要安装 node 和 npm ,这里同样采用nvm的形式安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash source ~/.bashrc nvm list-remote nvm install v10.16.0 node -v
安装好nvm后,就可以使用npm 安装插件了
npm install --save markdown-toc
# 0x01 命令行
经常使用markdown 的玩家一定很想要一个自动生成的导航栏吧,自己写的基本思路就是
轮询监听滚动条的位置,通过抛锚和跳锚实现,这里介绍一下今天的主角,markdown-toc插件:
这个插件带Cli命令,使用帮助如下
markdown-doc [选项] <输入>
<输入> 表示需要使用 TOC 的 markdown 文件,可以通过标准输入读取
[选项]
-i | 直接往 <输入> 的文件注入TOC标识符: <!-- toc -->,如果没有这个参数就输出到屏幕,不修改md文件 |
--json | 通过json格式打印TOC |
--append | 在字符串的后面追加TOC |
--bullets | 指定需要被生成TOC项的标识符号,可以指定多个: --bullets "*" --bullets "+" |
--maxdepth | TOC最大深度,就是可以折叠多少层,默认6层 |
--no-stripHeadingTags | 在强力功能前,不删去标题无关的HTML标签 |
# 0x02 亮点
经常使用markdown 的玩家一定很想要一个自动生成的导航栏吧,自己写的基本思路就是
轮询监听滚动条的位置,通过抛锚和跳锚实现,这里介绍一下今天的主角,markdown-toc插件:
特点:
1. 可根据自己的需求生成TOC模板
2. 对重复标题生效
3. 默认采用sane,也可以自己定制
4. 过滤器可以筛掉你不想要的标题
5. 导入期可以导入你想加入的标题
6. 可以使用强劲的函数来改变链接生成
7. 可作为 remarkable 的插件使用
很安全:
不会像其他TOC生成器一样,破坏前面的内容,或将前面的内容属性误认为标题
# 0x03 用法
经常使用markdown 的玩家一定很想要一个自动生成的导航栏吧,自己写的基本思路就是
轮询监听滚动条的位置,通过抛锚和跳锚实现,这里介绍一下今天的主角,markdown-toc插件:
var toc = require('markdown-toc'); toc('# One # Two').content; // Results in: // - [One](#one) // - [Two](#two)
为了自定义输出,下面有几个属性将会返回
- content 自动生成导航导航的内容,你可以自定义样式
- highest 找到最高的等级标题,用于重新调整缩进
- tokens 可自定义的标题符号
# 0x04 API
1 - toc.plugin
作为 remarkable 插件使用,如下:
var Remarkable = require('remarkable'); var toc = require('markdown-toc'); function render(str, options) { return new Remarkable() .use(toc.plugin(options)) // <= register the plugin .render(str); }
使用实例
var results = render('# AAA
# BBB
# CCC
foo
bar
baz');
2 - toc.json
可生成json格式的TOC对象
toc('# AAA ## BBB ### CCC foo').json; // results in [ { content: 'AAA', slug: 'aaa', lvl: 1 }, { content: 'BBB', slug: 'bbb', lvl: 2 }, { content: 'CCC', slug: 'ccc', lvl: 3 } ]
3 - toc.insert
在想插入TOC的位置写上 <!-- toc --> 或者 <!--toc--> 内容 <!--tocstop-->
(使用注释作为占位符可以避免破坏原本的代码)
<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->
## abc
This is a b c.
## xyz
This is x y z.
结果是
<!-- toc --> - [abc](#abc) - [xyz](#xyz) <!-- tocstop --> ## abc This is a b c. ## xyz This is x y z.
4 - 通用函数
为了方便给想定制TOC的用户folk一份,插件提供了一些通用函数
toc.bullets()
: 通过数组获取标题标记符toc.linkify()
: 链接到一个标题字符toc.slugify()
: 从标题字符中应用强力函数toc.strip()
: 从标题字符中去掉某些字符
例子
var result = toc('# AAA ## BBB ### CCC foo'); var str = ''; result.json.forEach(function(heading) { str += toc.linkify(heading.content); });
# 0x05 选项
经常使用markdown 的玩家一定很想要一个自动生成的导航栏吧,自己写的基本思路就是
轮询监听滚动条的位置,通过抛锚和跳锚实现,这里介绍一下今天的主角,markdown-toc插件:
1 - 追加 (append)
追加一些字符串到匹配的标题标识符后面
toc(str, {append: ' _(TOC generated by Verb)_'});
2 - 过滤 (filter)
类型: 函数
默认: undefined
参数:
str 命中的标题字符串
ele 标题记号对象
arr 所有的标题对象
过滤掉一些极端的匹配命中的标题,如下就是一个坏标题
[.aaa([foo], ...) another bad heading](#-aaa--foo--------another-bad-heading)
为了去除这种极端的情况,可以使用过滤器筛掉
function removeJunk(str, ele, arr) { return str.indexOf('...') === -1; } var result = toc(str, {filter: removeJunk}); //=> beautiful TOC
3 - 强劲(slugify)
类型: 函数
默认: 默认替换掉特殊符号
例子
var str = toc('# Some Article', {slugify: require('uslug')});
4 - 符号(bullet)
类型: 字符或者数组
默认: *
就是层叠的列表符号,传入数组 ['*', '-', '+']
5 - 首项 (first1)
类型:布尔
默认: true
排除文件中的第一个h1级标题。这样可以防止自述文件中的第一个标题出现在TOC中
6 - 最大深度 (first1)
类型: 数字
默认: 6
最大深度
6 - 去除头部标签(stripHeadingTags)
类型:布尔
默认: true
去除多余的标记,类似github 的 markdown 表现