github-flavoured-markdownの自動目次

Github Flavored Markdownを使用して自動目次を生成することは可能ですか？

github-flavored-markdownのtocを生成する2つのオプションを作成しました。

DocTocコマンドラインツール（ソース）には node.js

npm install doctoc

npx doctoc . 現在およびすべてのサブディレクトリ内のすべてのマークダウンファイルに目次を追加します。

DocToc WebApp

最初にオンラインで試してみたい場合は、doctocサイトにアクセスし、マークダウンページのリンクを貼り付けると、マークダウンファイルの上部に挿入できるコンテンツのテーブルが生成されます。

Github Wikiとアンカー

以下のコメントでMatthew Flaschenが指摘したように、そのWikiページでは、GitHubは以前はdoctoc依存するアンカーを生成しませんでした。

更新：ただし、この問題は修正されました。

GitHub Pages（基本的にはJekyllのラッパー）は、Marukuのすべてを実装するkramdownを使用しているように見えるため、属性を介して自動的に生成される目次をサポートしています。toc

* auto-gen TOC:
{:toc}

最初の行は、順序付けられていないリストを開始するだけで、実際には破棄されます。

これにより、ドキュメントのヘッダーを使用して、ネストされた順序なしリストのセットが生成されます。

注：これは、コメントやWikiページで使用されているGitHub Flavored Markdown（GFM）ではなく、GitHubページで機能するはずです。私の知る限り、そのためのソリューションは存在しません。

VimでMarkdownファイルを編集する場合は、このプラグインvim-markdown-tocを試すことができます。

使い方は簡単で、目次を追加したい場所にカーソルを移動して実行するだけです :GenTocGFMです。

スクリーンショット：

特徴：

1. Markdownファイルのtocを生成します。（GitHubフレーバーマークダウンとレッドカーペットをサポート）

2. 既存の目次を更新します。

3. 保存時にtocを自動更新します。

自動ではありませんが、Notepad ++正規表現を使用しています。

すべてを最初から2番目に置き換えます（ヘッダーのないすべての行を削除します）

^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n

次に（ヘッダーIIIをスペースに変換します）

-##
        -

次に（ヘッダーIIをスペースに変換します）

-#
    -

次に（リンクタイトルの最初と最後にある未使用の文字を削除します）

\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]

次に（最後のトークンをスペースではなく小文字とダッシュに変換します）

\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2

未使用の最後のポンドと最初のダッシュを削除します。

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

リンクの不要な文字を削除します。

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

最後に、最終的なリンクを括弧で囲みます。

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

そして、ほら！十分な時間繰り返しれば、これをグローバルマクロに入れることもできます。

提案された回避策を除いて、それは不可能です。

Kramdown TOC拡張とsupport@github.comとStevenへの他の可能性を提案しました！ラグナロクはいつもと答えた：

提案とリンクをありがとう。チームが確認できるように、それを社内の機能リクエストリストに追加します。

それが起こるまでこの質問を賛成しましょう。

もう1つの回避策は、目次をレンダリングする Markdownの代わりにAsciidocを使用することです。私は最近、自分のコンテンツに対してこのアプローチに移行しました。

Github Flavored Markdownは、MarkCarpetエンジンとしてRedCarpetを使用しています。RedCarpetリポジトリから：

：with_toc_data-各セクションにリンクできるように、出力HTMLの各ヘッダーにHTMLアンカーを追加します。

このフラグを設定するにはレンダラーレベルで取得する必要があるようですが、これは明らかにGithubでは不可能です。ただし、Githubページの最新の更新では、ヘッダーの自動アンカーがオンになっていて、リンク可能な見出しが作成されているようです。正確には望みどおりではありませんが、ドキュメントの目次を（手動ではありますが）少し簡単に作成できる場合があります。

Visual Studio Codeで作業するときにmardownファイルの目次を作成する非常に便利な方法は、Markdown-TOC拡張機能です。です。

既存のマークダウンファイルに目次を追加し、保存時に目次を最新の状態に保つこともできます。

ファイルからhttp://documentup.com/で Webページを自動的に生成することが可能README.mdです。TOCを作成するのではありませんが、多くの場合、TOCを作成する理由を解決できる可能性があります。

：Documentupの別の選択肢はFlatdocあるhttp://ricostacruz.com/flatdoc/

Gitdownは、Githubのマークダウンプリプロセッサです。

Gitdownを使用すると、次のことができます。

• 目次を生成する
• デッドURLとフラグメント識別子を見つける
• 変数を含める
• インクルードファイル
• ファイルサイズを取得する
• バッジを生成する
• 印刷日
• リポジトリ自体に関する情報を出力する

Gitdownは、GitHubリポジトリのドキュメントページの管理に関連する一般的なタスクを合理化します。

使い方は簡単です：

var Gitdown = require('gitdown');

Gitdown
    // Gitdown flavored markdown.
    .read('.gitdown/README.md')
    // GitHub compatible markdown.
    .write('README.md');

個別のスクリプトとして、またはビルドスクリプトルーチン（Gulpなど）の一部として含めることができます。

使用coryfklein / doctoc、のフォークthlorenz / doctoc「を追加しないで生成 DocToc内容のすべてのテーブルに」。

npm install -g coryfklein/doctoc

同僚の@schmiedcと私は、TOCボタンの左側に新しいボタンをインストールするGreaseMonkeyスクリプトを作成しました。このスクリプトh1は、優れたmarkdown-jsライブラリを使用して目次を追加/更新します。

doctocのようなソリューションに対する利点は、GitHubのwikiエディターに統合され、ユーザーがコマンドラインで作業する必要がない（そしてユーザーが次のようなツールをインストールする必要がある）ことです。 node.js）ことです。Chromeでは、拡張機能ページにドラッグアンドドロップすることで機能します。Firefoxでは、GreaseMonkey拡張機能をインストールする必要があります。

プレーンマークダウンで機能します（つまり、マークダウンのGitHub拡張であるため、コードブロックを正しく処理しません）。貢献を歓迎します。

多くの人々が回避策を提供しているので、これはこの質問に対する直接の回答ではありません。TOCの生成がGithubによって公式にサポートされているとはまだ思っていません。GitHubのGFMプレビューページに目次を自動的に表示させたい場合は、機能のリクエストに関する公式の問題に関するディスカッションに参加してください。

現在、マークダウン構文を使用することはできません（GitHubで進行中のディスカッションを参照）。ただし、次のような外部ツールを使用できます。

• コンテンツジェネレーターのオンラインテーブル（raychenon / play-table-of-contents）
• arthurhammer / github-toc -GitHubリポジトリに目次を追加するブラウザ拡張

または、AsciiDoc代わりに（例README.adoc）を使用してください。

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

## A

### A2

## B

### B2

このコメントで示唆されているように。こちらのデモを確認してください。

GithubのTexteditor Atomについては、この素晴らしいプラグイン（またはAtom-lingoの「パッケージ」）をチェックしてください。このプラグインは、「解析済みマークダウンから見出しのTOC（目次）」ファイルを生成します。

マークダウン目次

Atomパッケージとしてインストールしたら、ショートカットctrl-alt-cを使用して、markdown-doc-structureに基づく目次を現在のカーソル位置に挿入できます...

スクリーンショット：

Atomキーバインド

markdown-tocは、Atomのプラグインを制御するための次のデフォルトのキーバインディングを提供します。

• ctrl-alt-c =>カーソル位置に目次を作成
• ctrl-alt-u => TOCを更新
• ctrl-alt-r => TOCを削除

プラグインの機能（プロジェクトのREADMEから）

• アンカータグによる自動リンク、例えば # A 1→#a-1
• depthFrom:1およびによる深度制御[1-6]depthTo:6
• とのリンクを有効または無効にする withLinks:1
• 保存時にリストを更新 updateOnSave:1
• 順序付きリスト（1. ...、2。...）を orderedList:0

これは私が今日一緒にこれのために投げたシェルスクリプトです。必要に応じて調整する必要があるかもしれませんが、それは良い出発点になるはずです。

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/^#//'

最終的な＃置換を行うためのより良い方法を誰かが知っている場合は、コメントを追加してください。いろんなことを試してみて満足できなかったので、無理矢理強制しました。

これを実現するGitHubアクションがあります。

https://github.com/marketplace/actions/toc-generator

1. TOC（オプション）の場所を指定します。 README.md

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

2. セットアップワークフロー .github/workflows/toc.yml

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

他の回答の大半は、ツールをインストールする必要があります。すばやく簡単なオンラインソリューションhttps://imthenachoman.github.io/nGitHubTOCを見つけました。

マークダウン入力の場合は、コンテンツ出力のテーブルを生成します。最小および最大の見出しレベルを指定できます。

ソースコードはhttps://github.com/imthenachoman/nGitHubTOCにあります