GitHub wikiである種の目次を作成するにはどうすればよいですか?


102

ここを見ると:http : //en.wikipedia.org/wiki/Stack_Overflow

「コンテンツ」セクションが少しあることに気づくでしょう。リンクの1つをクリックすると、ページの特定のセクションに移動します。

GitHub wikiでこれを行うにはどうすればよいですか?マークダウンまたは彼らが使用するもので?


3
関連はありますが、完全に重複しているわけではありません。詳細は次のとおりです。stackoverflow.com
Jon Adams

回答:


111

これは、Markdownチートシートの目次でうまく示されています。

##### Table of Contents  
[Headers](#headers)  
[Emphasis](#emphasis)  
...snip...    
<a name="headers"/>
## Headers

GitHub Markdownファイルのヘッダーにカーソルを合わせると、その左側に簡単な小さなリンクが表示されます。そのリンクを使用することもできます。そのリンクの形式は<project URL#<header name>です。<header name>すべて小文字でなければなりません。


36
MediaWikiの_ _ TOC _ _のように自動生成する方法は確かにありますか?
LB-- 2014

17
@ LB--:GitHub wikiページを編集して、「編集スタイル」ドロップダウンを「MediaWiki」に変更すると、MediaWikiを__TOC__直接使用できます。明らかに、基礎となる自動生成ロジックがあります。しかし、機能はMarkdown編集スタイルでは公開されていないようです。かなり残念です。すべての機能のリクエストを送信してみましょう。おそらくオンにするでしょう。
Andrew Janke、2015

3
私はそこにある「基礎となる自動生成ロジック」に立ち向かう。さまざまな「編集スタイル」がさまざまなレンダラーを通過するように見えます。それでも、MDバージョンでこれを使用することは非常に人気があり、追加するのが難しくないので、すばらしいことです。
Andrew Janke 2015

5
@AndrewJankeもっと調べたところ、MarkDown形式では目次の自動生成がサポートされていないようで、彼らはそれを誇りに思っています。
LB--2015

6
リンクの作成には1つの問題があります。小文字でなければなりません。私はそれを知らなかったので、なぜ私の目次が機能しないのかと思っていました。の#Headers代わりに使用しました#headers。それはあなたの答えのタイプミスだと思いました。おそらく、この情報を回答に追加できます。
t3chb0t 2015

20

可能な(半自動化された)ソリューションの1つは、Eugene Kalininのソリューションですgithub-markdown-toc。このツールは基本的にREADME.mdファイルをクランチし#、TOCを作成するために見出しを削り取ります。

  1. スクリプトをダウンロードhttps://github.com/ekalinin/github-markdown-toc
  2. README.mdスクリプトにあなたを養う(ユージーンので述べたようにREADME.md

    猫README.md | bash github-markdown-toc

  3. 生成された目次をカットアンドペーストして、README.mdファイルの上部に配置します

このbash実装はLinuxでのみ機能することに注意してください(私が知る限り)。

余談ですが、golangの実装があり、おそらく動作せるのにもっと面倒です。




12

現在、マークダウン構文()を使用してそれを行うことはできません.md。いくつかのアイデアを一覧表示するような、レンダリングされたマークダウンファイルに目次TOC自動的に生成することに関する非公式の議論が進行中README.mdです。

ただし、次のような他の回避策があります。


1
はい、私は主に目次とヘッダーへのリンクのためにasciidocに変換されました。Markdownが追いつくのを待つことにうんざりしました。
Ciro Santilli郝海东冠状病六四事件法轮功

8

Markdownに固執する立場にない場合は、以下のようにすることができます。

  • のGitHub /ウィキ:切り替え値下げをするのMediaWiki__TOC__構文を使用します。サンプルを参照してください。
  • GitHubの/レポ:切り替え値下げをするAsciiDoc:toc:構文を使用します。デモを参照してください。

ただし、GitHub / repoのMarkdownファイルを使用すると、WikipediaのようにGitHubページで取得できます。

  • ときジキルが活性化され、それが生成GitHubのページを使用してKramdownをデフォルトで
  • Kramdownにはが付属していTable Of Contentます。{:toc}構文を使用します。説明を参照してください。

5

Visual Studioコード

Visual Studio Codeをたまたま使用した場合、Markdown All in Oneと呼ばれる使いやすい拡張機能があり、.mdファイルのTOCを瞬時に作成できます。

ここに画像の説明を入力してください

コマンドパレット(Ctrl-Shift-P)を開くだけ->Markdown: Create Table of Contents

オリジナルmd 自動目次挿入後

自動更新により、編集した目次が混乱しますか?

追加のヒントとして、次のコマンドを使用して「保存時のTOCの自動更新」をオフにすることができます。

  "markdown.extension.toc.updateOnSave": false,

Visual Studioの設定で(コマンドパレット-> [設定]:[設定を開く(JSON)])。



2

githubには、Markdownを処理した後、htmlバージョンのh1、h2、h3などのヘッダーにid = ".."属性を生成する独自の方法があるため(たとえば、Bitbucketは、 id = "slug")ホイールを再発明せずに、このプロセスをリバースエンジニアリングしたライブラリを使用すると便利です。

markdown-tocと呼ばれる、このタスク用の非常に優れたライブラリが1つ見つかりました。

私のマシンには常にノードをインストールしているので、私にとってはそれが最善の解決策のようです。

npx markdown-toc -i file.mdを実行するだけです

そして、それは、少なくともnode.jsエコシステムにおいて、このタスクのためのより一般的なツールの1つであるように見えます。

ls
cat <<EOF >> test.md | tee 
## Table of Contents

<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
EOF
ls
cat test.md
npx markdown-toc -i test.md
cat test.md

出力:

ここに画像の説明を入力してください

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.