Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
src
 
 
 
 
 
 
 
 
 
 

README.md

警告

因为该工具添加目录时是会在原来的文章中直接添加和刷新, 有损坏文章本身的风险, 请一定保存好原版文章(比如在git中commit过了)后再使用, 本人不因为你使用该工具造成的损害负责, 千万注意.
事实上我就出现过修改后的文章用vim打开乱码的情况, 但是通过atom编辑又是正确的情况

以下目录即用本工具生成:

目录:

为什么需要一个这样的工具

我的博客原来是有目录生成工具的, 依赖的是Kramdown(好像是)这个Markdown解析引擎, 但是这个解析引擎有些其他的问题(忘了什么问题了, 印象中是代码块解析不好), 所以我后来换成了Redcarpet, Redcarpet支持TOC, 但是只是在生成的HTML中含有每个目录的id, 而没有TOC本身的生成功能, 网上有很多解决方案, 不管是用Javascript动态生成还是静态生成, 都有些不太好的地方, 具体就不展开说了. 反正是能搜到很多, 但是我发现实际能用的没有一个.

原理

这个工具, 目录内容本身是基于分析文章本身, 并且只分析两层, 即以#和##开头的标题.

目录的链接基于Redcarpet这个生成工具生成的HTML, 在分析目录的时候, 会跳过~~~标注的代码(其他形式的代码块, 要是是类似Ruby这种注释也是#开头的, 会把代码的注释看作是文章的标题.)

实现的方式是在<!-- more -->标签后, 添加成对的<!-- toc-begin -->, <!-- toc-end -->标签, 实际目录在两个标签中.

安装及使用

Github上下载源码, 在target/release目录中有编译好的程序. 实际使用的时候, 用文件名作为参数执行程序, 即可:

$./toc-auto-add filename.md

假如想要执行多个文件, 可以一次传递进去, 如下面这样:

$./toc-auto-add filename1.md filename2.md filename3.md

假如想要执行目录下非常多的文件, 就没有在本程序中实现了, 按照Unix的哲学, 你可以使用其他程序组合起来使用, 比如下面这样, 就是转换本目录下所有的md文件:

$ls *.md | xargs -tI {} ./toc-auto-add {}

需要重复执行的话, 请用上面的命令自行制作sh文件即可.

使用须知

对于没有耐心看完原理的人, 也不会自己去修改源代码满足自己需求, 希望直接用, 需要理解这个工具因为是为我自己写的, 所以有比较强的环境依赖, 需要满足以下条件:

  1. 需要有<!-- more -->锚点, 工具才知道把toc添加到什么位置
  2. 要想文章后的链接有效, 必须使用redcarpet这个markdown的html生成引擎
  3. 假如有代码的话, 请用~~~这种形式, 也就是老外说的fenced code blocks形式
  4. 我分析文章实际是没有markdown那么强大, 就是简单的文本分析, 请在标题中不要再使用类似**强调这种markdown语法了, 会导致链接生成错误
  5. 添加一次以后, 文章更新以后, 只要保证toc区域没有被破坏, 可重复执行以刷新toc内容

假如你同样是使用Github Pages, 那么相关配置大概是这样子的:

markdown:      redcarpet
markdown_ext:  md

excerpt_separator: "<!-- more -->"

redcarpet:
  extensions: ["fenced_code_blocks", "with_toc_data"]

About

auto add toc(table of content) for markdown article, support github page.

Resources

Releases

No releases published

Packages

No packages published

Languages