235

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

4

18 に答える 18

154

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

DocToc コマンド ライン ツール (ソース) にはnode.jsが必要です

インストール:

npm install -g doctoc

使用法：

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

DocToc ウェブアプリ

最初にオンラインで試してみたい場合は、doctocサイトに移動し、マークダウン ページのリンクを貼り付けると、マークダウン ファイルの先頭に挿入できる目次が生成されます。

Github Wiki とアンカー

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

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

于 2012-05-27T02:37:45.800 に答える
26

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

* auto-gen TOC:
{:toc}

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

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

注:これは、コメントや wiki ページで使用される GitHub Flavored Markdown (GFM) ではなく、GitHub ページで機能するはずです。私の知る限り、そのための解決策は存在しません。

于 2012-03-27T22:16:28.913 に答える
15

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

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

スクリーンショット:

vim-markdown-toc

特徴：

  1. Markdown ファイルの toc を生成します。(GitHub Flavored Markdown と Redcarpet をサポート)

  2. 既存のトピックを更新します。

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

于 2016-09-18T10:25:42.257 に答える
11

2021 年 3 月の更新: GitHub が公式の回避策を追加しました

README を下にスクロールすると、次のような ToC が表示されるようになりました。

ここに画像の説明を入力

デモ: https://github.com/cirosantilli/test-git-web-interface/tree/master/d

より良い Ctrl + F を望んでいたように、ドキュメント内でレンダリングされませんが、何もないよりはましです。

README 以外でも機能します。例: https://github.com/cirosantilli/test-git-web-interface/blob/master/md.md

また、リポジトリ設定を追加して、それを無効にします。とても奇妙です。誰がそれを無効にしたいと思うでしょうか? https://github.com/cirosantilli/test-git-web-interface/settings機能の下:

目次

このリポジトリ内の Markdown ファイルの目次を自動生成します。目次は、ファイルの上部近くに表示されます。

元の答え

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

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

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

それが起こるまで、この質問に賛成票を投じましょう。

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

于 2014-06-22T06:46:39.550 に答える
8

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

:with_toc_data - 出力 HTML の各ヘッダーに HTML アンカーを追加して、各セクションへのリンクを許可します。

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

于 2012-05-24T17:44:34.150 に答える
4

ファイルからhttp://documentup.com/の Web ページを自動生成することが可能です。README.mdTOC を作成するわけではありませんが、多くの人にとって、TOC を作成したい理由が解決される可能性があります。

Documentup の別の代替手段は Flatdoc です: http://ricostacruz.com/flatdoc/

于 2013-04-09T19:45:54.000 に答える
3

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など) の一部として使用することもできます。

于 2014-11-22T15:50:35.823 に答える
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/^#//'

これらの最後の # 置換を行うより良い方法を誰かが知っている場合は、コメントを追加してください。いろいろ試してみましたが、どれも満足できなかったので、力ずくでやってみました。

于 2019-08-17T05:38:30.223 に答える