Markdown使用TOC自動生成導航欄

常常使用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 表現