Markdown使用TOC自动生成导航栏

时间：2021-10-15 21:57:44

经常使用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\n\n# 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\n# BBB\n# CCC\nfoo\nbar\nbaz');




2 - toc.json


可生成json格式的TOC对象




toc('# AAA\n## BBB\n### CCC\nfoo').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\n## BBB\n### CCC\nfoo');

var str = '';

result.json.forEach(function(heading) {

  str += toc.linkify(heading.content);

});




# 0x05 选项


经常使用markdown 的玩家一定很想要一个自动生成的导航栏吧，自己写的基本思路就是


轮询监听滚动条的位置，通过抛锚和跳锚实现，这里介绍一下今天的主角，markdown-toc插件：


1 - 追加 (append)


追加一些字符串到匹配的标题标识符后面




toc(str, {append: '\n_(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 表现
相关文章