私の README が千行を越えたとき、私はみんながすることと同じことをしました。スクロールしました。その後、さらにスクロールしました。4 番目のパスのどこかで "Deployment" セクションを探していました。諦めて、ファイルの上部に目次を手書きし始めました。見出しの名前を変更し、リンクを更新するのを忘れて、"Configuration" が何も指していない README を出荷するまで、それはうまくいきました。自分のドキュメントのページ内リンクが壊れているのは小さなことですが、それは読者に誰も店のことを気にしていないことを伝えるような小さなことです。
私はブラウザベースの開発者ユーティリティの集まりである [Toolz.dev] (/) を構築し、Markdown: ツールガイド、READMEファイル、内部仕様、そして今読んでいるドキュメントをたくさん維持しています 手で維持しなければならない目次は、最終的には嘘をつく目次です そこで私は、 を構築しました Markdown TOC Generator 退屈な部分を毎回正しく行うために、このガイドはアンカー リンクを構築する際に私が学んだすべてです。
tl;dr: Markdown 目次は、同じページの見出しにジャンプするリンクのネストされたリストです。 links は、各見出しが自動アンカー id を取得するため機能し、GitHub が割り当てる slug は、テキストを小文字にする、ハイフン以外の句読点をドロップする、スペースをハイフンにするという特定のルールに従って、Markdown をジェネレーターに貼り付け、どの見出しレベルを含めるかを選択し、リストをコピーします。 tool は、正確な slugs GitHub レンダリングを計算します
-1重複した見出しには接尾辞が付いているため、貼り戻しても何も壊れません。
Markdown 目次とは何ですか?
Markdown の目次は特別な構文ではありません。 共通マーク はそのような構成を定義せず、GitHub Flavored Markdown も定義しない。 普通のリストで、すべての項目がリンクであり、すべてのリンクが同じドキュメント内のアンカーを指す。 GitHub のような Markdown レンダラーが見出しを HTML にすると、その見出しも与える id 属性。 と記される見出し ## Getting Started 荒れる <h2 id="getting-started">Getting Started</h2>.そのidが存在すると、 と書かれたリンク [Getting Started](#getting-started) ページをそこにスクロールします。
したがって、目次はそれらのリンクの単なるコレクションであり、見出し階層をミラーリングするためにインデントされています:
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
トリック全体はその例から一言で生きていますアンカーアンカーを間違えてリンクは黙って失敗しどこにもスクロールしません正しくしてコンテンツブロックはGitHubで動作しますほとんどの静的サイトジェネレーターで同じ慣習に従うドキュメントプラットフォーム内でハード部分はリストを書かないハード部分は各レンダラーが割り当てる正確なidを予測するので手作業で行うのは変更するあらゆるドキュメントで負けゲームです。
ヘディングアンカーは実際にどのように生成されていますか?
GitHub' s slug アルゴリズムは決定論的で記憶する価値があります、なぜなら、一度それを知れば、ページ上のすべてのアンカーを予測できるからです。 手順は、順番に、見出しのテキストを小文字に変換し、文字、数字、スペース、ハイフンではない文字を削除し、各スペースをハイフンに置き換えるという規則全体です。
その結果は人々が旅行する場所です。 のような見出しを考えてみましょう ## Set Up & Config。 lowercasing は与える set up & config。アンパサンドを削除すると (ただし、その周囲のスペースは残します)、次のようになります set up config 2つのスペースがあります & 昔は.空間をハイフンにすると が生成される set-up--config、ダブルハイフンを使って。 そのダブルハイフンは間違いのように見えますが、それはまさに GitHub がレンダリングするものなので、それはまさにあなたのリンクが必要とするものです。 " cleans up" ダブルハイフンは解決しないリンクを生成します。
句読点の多い見出しは予想よりもさらに崩れます。 ## C++ Guide なる c-guide、両方のプラス記号が剥がされ、余ったスペースが単一のハイフンになるためです。 ## What's New? なる whats-new、アポストロフィと疑問符が消えるからです。 絵文字とほとんどの記号は完全に消えます。 the Markdown TOC Generator このルール文字を文字に適用すると、github が構築する id である slug が示され、推測は関係ありません。
2 つの見出しが同じ場合はどうなりますか?
ドキュメントは見出しを繰り返します。 changelog には、3 つのセクションがあり、すべてタイトルが付けられている場合があります ### Fixed。 1つ1つが slug を生成した場合 fixed、最初のリンクだけが動作します。 GitHubは重複する部分に番号を付けることでこれを解決します: 最初の Fixed 取得 fixed、 2 つ目 得る fixed-1、 3 つ目 得る fixed-2、 などとドキュメント順に並べた。 接尾辞は基底 slug の後にハイフンで付加される。
これは、手書きの目次が同期から外れる最も一般的な理由の1 つです。 すでに使用した名前の2 番目のセクションを追加すると、アンカーは静かになります -1、そしてあなたの古いリンクは今間違った場所かどこにもまったく指していない。 generatorはそれが放ったすべてのslugを追跡し、同じ数値接尾辞を適用するので、繰り返し見出しは正しい発生にリンクする。
ツールはどのような見出しを読み取りますか?
Markdownには2 つの見出しスタイルがあり、完全なジェネレーターは両方を読み取る必要があります。 一般的なものはATXで、行は1 から6 で始まります # 文字の後に見出しのテキストが続きます。 ハッシュのカウントはレベルなので、 # は H1 および ###### は H6 です。 2 番目のスタイルは Setext で、次の行にテキスト行に下線が引かれ、H1 の場合は等号、H2 の場合はハイフンが付けられます:
Document Title
==============
A Section
---------
どちらのスタイルもアンカーidを持つ見出しを生成するため、どちらも目次に属します。 setextのトリッキーな部分は、ハイフンの行がどちらかを意味する可能性があるため、水平ルールとは別に、実際の下線付き見出しを伝えています。ジェネレータが使用するルールは、ハイフンの下線は、その真上の行が通常の段落テキストであり、空白行、リスト項目、ブロッククォート、または別のブロック構成ではない場合にのみ見出しとしてカウントされます。 A --- 周囲に空白の線を引いて一人で座ることはテーマ別の休憩であり、正しく無視されます。
扱うべきカテゴリがもう1 つあり 素朴な道具を静かに台無しにするカテゴリです コード内の見出しです ドキュメントにシェルコマンドを示す フェンス付きのコードブロックが含まれている場合 それらの行のいくつかは で始まります # コメントとして.これらは見出しではなく,決して内容に現れてはならない.ジェネレータは柵で囲まれたコードブロック (トリプルバックティックやトリプルチルダで区切られたもの) を追跡し,任意のものをスキップする. # それらの中に行を。 のようなシェルコメント # install dependencies 例では、その例に属するもののままです。
目次の深さを制御するにはどうすればよいですか?
H6 までのすべての見出しをリストした目次は目次ではなく、文書の 2 番目のコピーです。ほとんどの README は、内容が H2 と H3 のみをカバーする場合に最もよく読み、読者に主要なセクションとその直接の子供たちを詳細に溺れさせることなく提供します。ジェネレーターを使用すると、最小レベルと最大レベルを設定でき、その範囲に含まれる見出しのみが含まれます。
ここでの微妙な挙動はインデントです H2 から H4 を含めると、保持した最も浅い見出しは H2 となり、目に見えない H1 が上にあるかのようにインデントするのではなく、左マージンに対して面一に配置する必要があります。ジェネレーターは、実際に含まれる最も浅い見出しに対するネスト深さを測定するため、H2 から始まるコンテンツ ブロックはインデントなしで始まります。これは、意図的に見えるリストと、最初の列を失ったように見えるリストの違いです。
リスト マーカーを選択することもできます。順序付けされていないリストは、すべてのエントリに箇条書きを使用します。これは、README の従来の外観です。順序付けされたリストはエントリに番号を付け、ジェネレータは各ネスト レベル内のカウントを再起動するため、番号付きのアウトラインは 1 から 50 までまっすぐにカウントするのではなく、正しく読み取られます。インデントは、ドキュメントの残りの部分が使用する内容に応じて、2 つのスペース、4 つのスペース、またはタブにすることができます。
アクセント付き見出しと非ラテン語見出しはどうですか?
すべての見出しが平易な英語であるわけではなく、slug ルールは対処しなければなりません。 GitHub は他のアルファベットの文字を剥ぎ取るのではなく、そのまま保持するので、次のような見出しになります ## Configuración アクセント付きの文字を保持し、 になります configuración、キリル文字またはギリシャ語の見出しはそれらの文字も保持します。削除されるのは文字に関係なく、文字ではなく句読点と記号です。ジェネレーターは、unicode 文字または数字を有効な slug 文字として扱うことで同じ原則に従うため、多言語ドキュメントは空のリンクの行ではなく、GitHub がレンダリングするものと一致するアンカーを生成します。
これは最初に現れたものよりも重要です スペイン語、ドイツ語、または日本語でドキュメントを書くチームは、多くの場合、ナイーブな slug ツールが見出しを使用できないアンカーにマングルしていることに気づきます。 、それらのツールは ASCII を前提としているため、翻訳された README 上でリンクが何も指していない場合、非 ASCII 文字を静かに破棄した slug がほぼ確実にその理由です。 unicode 対応ツールでコンテンツ ブロックを生成すると、壊れたリンクのクラス全体が削除され、同じドキュメントがアンカーを失うことなく複数の言語で見出しを保持できることを意味します。
生成された TOC と自動 TOC はいつ使用すればよいですか?
いくつかのプラットフォームはあなたのために目次を構築します。 gitlabは、をサポートしています [[_TOC_]] トークン、一部の Wiki はコンテンツ ボックスを自動的に挿入し、Docusaurus などのドキュメント フレームワークは何も書かずに見出しからページ上のアウトラインをレンダリングします。これらのシステムの 1 つ内で作業している場合は、組み込み機能を使用します。プラットフォームがすべてのレンダーで再生するため、労力はゼロで最新の状態を維持します。
ジェネレーターは、他のどこでもその場所を獲得し、"everywhere else" は大きな場所です。 GitHub README はコンテンツ ブロックを自動生成しないため、リポジトリのランディング ページには、ファイルにコミットされた実際の Markdown リストが必要です。他のものに変換されたり、電子メールで送信されたり、問題に貼り付けられたり、最小限のビューアでレンダリングされる Markdown には、オンザフライで構築するエンジンがないため、静的なコンテンツ ブロックが必要です。以下の表は、各アプローチが適合する場所を示しています。
| 状況 | 最良のアプローチ | なんでや |
|---|---|---|
| GitHub README | 生成された静的リスト | GitHub は見出し ID をレンダリングしますが、TOC を自動挿入しません |
| GitLab ウィキまたはドキュメント | [[_TOC_]] トークン |
ネイティブ、常に現在 |
| Docusaurus / MkDocsページ | 内蔵アウトライン | Framework は見出しからレンダリングします |
| エクスポート用のプレーン マークダウン ファイル | 生成された静的リスト | ビュー時に構築するレンダラーはありません |
| 問題またはプルリクエストの説明 | 生成された静的リスト | アンカーは機能しますが、リストを自動生成するものは何もありません |
経験則: Markdown を表示するものがコンテンツ自体をビルドできる場合は、そのままにしておきます。 Markdown が読み取れない場所で読まれる可能性がある場合は、リストを生成してコミットします。形式間で変換するときは、 HTML への Markdown 変換 そして、 HTMLからMarkdownへのコンバーター アンカーは往復でも生き残るため、生成されたコンテンツ ブロックと自然に対になります。
これはMarkdownワークフローの残りの部分にどのように適合しますか?
目次は、長いドキュメントを読みやすくするための 1 つの部分であり、いくつかの習慣と並行して最も効果的です。見出しの名前が変更されると、その見出しへのリンクが変更され、その見出しを指すすべてのリンクが切断されるため、見出しのテキストを安定に保ちます。名前を変更するときは、ファイルのさらに下に重複接尾辞の番号付けが移動することが多いため、覚えている 1 つのリンクを編集するのではなく、内容を再生成します。
構造化コンテンツは、同じファミリーの他のツールから恩恵を受けます。ドキュメントが表形式のデータに傾いている場合、 マークダウン テーブル ジェネレーター 手入力テーブルがほとんど正しくならないように正しく整列したパイプテーブルを構築します。 clean Markdownになる必要がある乱雑なHTML、またはHTMLになる必要があるクリーンなMarkdownを継承する場合、コンバータは見出し構造を維持しながら翻訳を処理します。そして、長さまたはキーワードのバランスについて文書を監査している場合は、 ワードカウンター クラウドベースのものに下書きを貼り付けることなく、数値を提供します。
すべてブラウザで実行され、それは音よりも重要です READMEには、多くの場合、未発表の機能名、内部URL、またはクライアントの詳細が含まれており、リンクのリストを構築するためだけに、それらのどれもサードパーティのサーバーにアップロードされるべきではありません ジェネレータはクライアント側のJavaScriptでMarkdownを解析するため、ドキュメントがマシンから離れることはありません 開発者ツーリングにおけるプライバシーがあなたが考えるものである場合、上の書き込み データのプライバシーとオンライン ツール ローカル処理が正しいデフォルトである理由と、 Web 開発者ツールキット 私が毎日到達する残りのユーティリティをまとめます。
簡単に実行された例
この文書があるとします:
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
範囲をH2 からH3 に設定し、箇条書きのリストを選択し、アンカーリンクをオンにしたままにします。 ジェネレータは以下を生成します:
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
H1 タイトルは範囲より上にあり、H2 セクションは左にフラッシュされ、H3 の子供は 1 レベルインデントされるため除外されます。そのブロックを README にタイトルのすぐ下に貼り付け、すべてのエントリが GitHub のセクションにジャンプします。これが全体の仕事であり、この文を読むのにかかる時間で完了し、あなたの代わりにマシンが slugs を計算したため、正しいままです。
よくある質問
Markdown 目次はどのように機能しますか?
Markdown 目次は、同じページ内の見出しアンカーを指すリンクのリストです。 Markdown ドキュメントの各見出しには自動 ID が与えられ、リンクは次のように記述されます セクション そこにジャンプします このツールは 見出しを読み込み 一致するアンカーを構築し ネストしたリストを組み立てます。
アンカーリンクはどのように生成されますか?
アンカーは GitHub slug ルールに従います。見出しのテキストは小文字で、ハイフン以外の句読点は削除され、スペースはハイフンになります。 "Set Up & Config" id set-up-config になります。 2 つの見出しが同じ slug を生成すると、2 番目の見出しには -1 の接尾辞が付けられ、3 番目の見出しには -2 というように、GitHub のレンダリング方法に一致します。
GitHub READMEファイルで動作しますか?
はい。 slug アルゴリズムは、GitHubが見出しidをレンダリングするために使用するものをミラーリングするため、目次リンクはgithub.comのREADME内で正しく解決されます。 READMEを貼り付け、見出しレベルを選択し、生成されたリストをタイトルの下にドロップします。
どの見出しレベルが表示されるか選択できますか?
はい。たとえば、H2 から H4 までの最小レベルと最大レベルを設定し、その範囲の見出しのみが含まれます。ネスト深さは、含まれる最も浅い見出しに対して測定されるため、アウトラインが大きな空のインデントで始まることはありません。
コードブロック内の見出しは含まれていますか?
いいえ フェンスで囲まれたコード ブロック内の # で始まる行 (トリプル バックティックまたはトリプル チルドで区切られている) は見出しではなくコードとして扱われるため、スニペットやシェルのコメントの例は目次には表示されません。
順序付きTOCと順序なしTOCの違いは何ですか?
順序付けされていない目次は、すべてのエントリにハイフンなどの箇条書きマーカーを使用しますが、順序付けされた目次は、各ネスト レベル内で増加する数値を使用します。リーダーが番号付きのアウトラインの恩恵を受ける場合は順序付けを選択し、より軽量で従来の目次ブロックには順序付けされていないものを選択します。
ツールは Setext の見出しをサポートしていますか?
はい。 # で始まる ATX 見出しと Setext 見出しの両方を読み取ります。テキスト行には、H1 の等しい記号または H2 のハイフンで下線が引かれています。両方のスタイルは同じ方法でアンカー リンクに変換されます。
Markdown TOCジェネレータは無料でプライベートですか?
はい。サインアップも制限もなく完全に無料です。すべての解析はクライアント側の JavaScript を使用してブラウザで行われます。そのため、貼り付けた Markdown がデバイスから離れることはなく、ページが読み込まれるとツールはオフラインで動作し続けます。
