github风味降价中的自动TOC

是否可以使用？

GitHub Pages（基本上是Jekyll的包装器）生成自动目录，该页面因此支持via

toc

属性：

* auto-gen TOC:
{:toc}

第一行只是开始一个无序列表，实际上被丢弃了

这将使用文档中的标题生成一组嵌套的无序列表

---

注意：这应该适用于GitHub页面，而不是评论或wiki页面中使用的GitHub风格的标记（GFM）。AFAIK没有解决方案。

Github风格的降价使用红毯作为他们的降价引擎。 从：

：使用_toc_数据-将HTML锚添加到输出HTML中的每个标题， 允许链接到每个节

---

看起来您需要在渲染器级别设置这个标志，这在Github上显然是不可能的。然而，对于Github页面，似乎为标题启用了自动锚定，从而创建可链接的标题。这不完全是您想要的，但它可能会帮助您更轻松地为您的文档创建TOC（尽管是手动创建的）。

我创建了两个选项来为github风格的降价生成TOC：

DocToc命令行工具（）需要 安装：

npm安装-g doctoc

用法：

doctoc.

将目录添加到当前和所有子目录中的所有标记文件

doctocwebapp 如果您想先在线试用，请访问该网站， 粘贴降价页面的链接，它将生成一个 可以在标记文件顶部插入的内容

Github Wiki和锚 正如Matthew Flaschen在下面的评论中指出的那样，GitHub以前没有生成

doctoc

所依赖的锚

---

更新：但是，它们已修复。

可以从

README.md

文件自动生成网页。这不是创建TOC，但对于许多人来说，它可能会解决想要创建TOC的原因

---

Documentup的另一种替代方法是Flatdoc:

它不是自动的，但它使用记事本++正则表达式：

将第一行替换为第二行（删除所有没有标题的行）

然后（将标题III转换为空格）

然后（将标题II转换为空格）

然后（删除链接标题开头和结尾未使用的字符）

然后（将最后一个标记转换为小写和破折号，而不是空格）

删除未使用的最终磅数和初始破折号：

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

删除链接中的无用字符：

(\].*?)(?:\(|\))
\1

最后，在最终链接周围添加括号：

\](?!\()(.*?)$
\]\(\1\)

---

瞧！如果重复足够长的时间，您甚至可以将其放入全局宏中。

2021年3月更新：GitHub添加了一个官方解决方案

自述现在在向下滚动时显示如下ToC：

演示：

它不会像我希望的那样在文档内部呈现，以获得更好的Ctrl+F效果，但它总比什么都没有好

现在也适用于非自述文件，例如：

他们还添加了一个存储库设置来启用或禁用该设置。这太奇怪了，谁会想禁用它？在“功能”下：

目录

自动生成此存储库中标记文件的目录。目录将显示在文件顶部附近

原始答案

这是不可能的，除了提议的变通办法

I Kramdown TOC扩展和其他可能性support@github.com他照例回答说：

谢谢你的建议和链接。我将把它添加到我们的内部功能请求列表中，供团队查看

让我们投票表决这个问题，直到它发生

另一个解决方法是使用Asciidoc而不是降价。现在，我的内容采用了这种方法。

使用，一种不会在每个目录中添加“generated with”的分支

npm install -g coryfklein/doctoc

是Github的降价预处理器

使用Gitdown，您可以：

• 生成目录
• 查找无效URL和片段标识符
• 包含变量
• 包括文件
• 获取文件大小
• 生成徽章
• 打印日期
• 打印有关存储库本身的信息

Gitdown简化了与维护GitHub存储库文档页面相关的常见任务

使用它很简单：

var Gitdown=require（'Gitdown'）；
吉顿
//吉特唐风味的降价食品。
.read（'.gitdown/README.md'））
//GitHub兼容降价。
.write（'README.md'）；

---

您可以将其作为单独的脚本使用，也可以将其作为构建脚本例程的一部分（例如）。

我的同事@schmiedc和我创建了一个新的

TOC

按钮，安装在

h1

按钮左侧，该按钮使用优秀的

标记js

库添加/刷新目录

npm install -g coryfklein/doctoc

与doctoc等解决方案相比，它的优势在于它集成到GitHub的wiki编辑器中，不需要用户在命令行上工作（并且需要用户安装像

node.js

）这样的工具）。在Chrome中，它通过拖放到扩展页面来工作，在Firefox中，您需要安装GreaseMonkey扩展

---

它将与普通markdown一起工作（即，它不能正确处理代码块，因为这是markdown的GitHub扩展）。欢迎投稿。

如果您使用Vim编辑标记文件，可以尝试此插件

用法很简单，只需将光标移动到要附加目录的位置，然后运行

：GenTocGFM

，完成

截图：

特点：

为标记文件生成toc。（支持GitHub风味减价和红地毯）

更新现有toc

保存时自动更新toc

---

这并不是对这个问题的直接回答

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

(\].*?)(?:\(|\))
\1

\](?!\()(.*?)$
\]\(\1\)

npm install -g coryfklein/doctoc

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

cat README.md \
    | sed -e '/```/ r pf' -e '/```/,/```/d' \
    | grep "^#" \
    | tail -n +2 \
    | tr -d '`' \
    | sed 's/# \([a-zA-Z0-9`. -]\+\)/- [\1](#\L\1)/' \
    | awk -F'(' '{for(i=2;i<=NF;i++)if(i==2)gsub(" ","-",$i);}1' OFS='(' \
    | sed 's/^####/      /' \
    | sed 's/^###/    /' \
    | sed 's/^##/  /' \
    | sed 's/^#//'

<!-- START doctoc -->
<!-- END doctoc -->

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2