UP
SmartyPants 		前のページへ
Python-Markdown3.3.6 		次のページへ
WikiLinks

Table of Contents

《 初回公開：2022/03/26 , 最終更新：未 》

原文は

旧バージョンの記事は

【　目次　】

要約

The Table of Contents拡張機能は、Markdownドキュメントから目次を生成し、それを結果のHTMLドキュメントに追加します。
この拡張機能は、標準のMarkdownライブラリに含まれています。

構文

デフォルトでは、すべてのヘッダーには、ヘッダーのテキストに基づいて生成された一意のID属性が自動的に設定されます。
この例に注意してください。この例では、3つのヘッダーすべてが同じIDを持ちます。

#Header
#Header
#Header

結果：

<h1 id="header">Header</h1>
<h1 id="header_1">Header</h1>
<h1 id="header_2">Header</h1>

目次を表示するドキュメント内のマーカーを配置します。
次に、ドキュメント内のすべてのヘッダーのネストされたリストがマーカーに置き換わります。
マーカーのデフォルトは[TOC]なので、次のドキュメントは。

[TOC]

# Header 1

## Header 2

次の出力が生成されます。

<div class="toc">
  <ul>
    <li><a href="#header-1">Header 1</a></li>
      <ul>
        <li><a href="#header-2">Header 2</a></li>
      </ul>
  </ul>
</div>
<h1 id="header-1">Header 1</h1>
<h2 id="header-2">Header 2</h2>

マーカーがドキュメント内にある（または無効になっている）かどうかに関係なく、目次はMarkdownクラスの属性（toc）として利用可能です。
これにより、ページテンプレートの他の場所に目次を挿入できます。
例えば。

>>> md = markdown.Markdown(extensions=['toc'])
>>> html = md.convert(text)
>>> page = render_some_template(context={'body': html, 'toc': md.toc})

toc_tokens属性はMarkdownクラスでも使用可能であり、dictオブジェクトのネストされたリストが含まれています。
たとえば、上記のドキュメントはmd.toc_tokensに次のオブジェクトを作成します。

[
    {
        'level': 1,
        'id': 'header-1',
        'name': 'Header 1',
        'children': [
            {'level': 2, 'id': 'header-2', 'name': 'Header 2', 'children':[]}
        ]
    }
]

レベルはhnレベルを参照していることに注意してください。
つまり、<h1>はレベル1、<h2>はレベル2などです。
入力のレベルが不適切にネストされると、出力のネストが奇妙になる可能性があることに注意してください。

カスタムラベル

ほとんどの場合、目次のテキストラベルはヘッダーのテキストと一致する必要があります。
ただし、それが望ましくない場合もあります。
その場合、この拡張機能がAttribute Lists Extensionと組み合わせて使用され、data-toc-label属性がヘッダーで定義され、その後その属性の内容がテキストラベルとして目次項目のために使われる。
たとえば、次のマークダウンは：

[TOC]

# Functions

## `markdown.markdown(text [, **kwargs])` { #markdown data-toc-label='markdown.markdown' }

次の出力が生成されます。

<div class="toc">
  <ul>
    <li><a href="#functions">Functions</a></li>
      <ul>
        <li><a href="#markdown">markdown.markdown</a></li>
      </ul>
  </ul>
</div>
<h1 id="functions">Functions</h1>
<h2 id="markdown"><code>markdown.markdown(text [, **kwargs])</code></h2>

目次のテキストは、目次の文脈においてはるかにクリーンで読みやすいことに注意してください。
data-toc-labelはHTMLヘッダー要素に含まれていません。
また、ヘッダーにリンクするときにクリーンなURLを提供するために、IDが属性リストで手動で定義されていることにも注意してください。
IDが手動で定義されていない場合、IDは常にヘッダーのテキストから取得され、data-toc-label属性からは取得されません。

愚鈍人の独り言

data-toc-label属性を定義するとそれは目次におけるテキストとして扱われる。

使い方

一般的な拡張機能の使用法については、拡張機能を参照してください。
拡張機能の名前としてtocを使用します。
拡張機能の構成については、ライブラリリファレンスを参照してください。

出力を構成するために、次のオプションが提供されています。

  • marker:
    検索して目次に置き換えるテキスト。
    デフォルトは[TOC]です。
    空の文字列に設定すると、マーカーの検索が無効になります。
    これにより、特に長いドキュメントで時間を節約できる場合があります。
  • title:
    目次の<div>タグに挿入するタイトル。
    デフィルトはNone.
  • anchorlink:
    Trueに設定すると、すべてのヘッダーがそれ自体にリンクします。
    デフィルトはFalse。
  • anchorlink_class:
    リンクに使用されるCSSクラス。
    デフォルトはtoclinkです。
  • permalink:
    Trueまたは文字列に設定すると、各ヘッダーの最後に永続的なリンクが生成されます。
    Sphinxスタイルシートで役立ちます。
    Trueに設定すると、段落記号（¶または「＆para;」）がリンクテキストとして使用されます。
    文字列に設定すると、提供された文字列がリンクテキストとして使用されます。
  • permalink_class:
    リンクに使用されるCSSクラス。
    デフォルトはheaderlinkです。
  • permalink_title:
    永続リンクのタイトル属性。
    デフォルトはPermanent linkです。
  • baselevel:
    ヘッダーの基本レベル。
    デフォルトは1です。
    基本レベル設定を使用すると、HTMLテンプレートの階層内に収まるようにヘッダーレベルを自動的に調整できます。
    たとえば、ページのマークダウンテキストにレベル3（<h3>）より高いヘッダーが含まれていてはならないとします。
    以下はそれを達成します：
    >>>  text = '''
... #Some Header
... ## Next Level'''
>>> from markdown.extensions.toc import TocExtension
>>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)])
>>> print html
<h3 id="some_header">Some Header</h3>
<h4 id="next_level">Next Level</h4>'
  • slugify:
    アンカーを生成するために呼び出すことができます。
    デフォルト：markdown.extensions.headerid.slugify
    別のアルゴリズムを使用してid属性を定義するには、次の2つの引数を取るcallableを定義して渡します。 　
    • value:

      slugifyする文字列。 　

    • separator:

      ワードセパレータ。 　
      呼び出し可能オブジェクトは、HTMLのid属性での使用に適した文字列を返す必要があります。
      Unicode文字列をサポートするデフォルトの呼び出し可能ファイルの代替バージョンもmarkdown.extensions.headerid.slugify_unicodeとして提供されています。

    愚鈍人の独り言

    slugifyとは

  • separator:
    単語の区切り文字。 idの空白を置き換える文字。 デフォルトは「-」です。
  • toc_depth:
    目次に含めるセクションレベルの範囲を定義します。
    単一の整数（b）は、下部セクションレベル（<h1> .. <hb>）のみを定義します。
    間にハイフンで区切られた2桁の文字列（ "2-5"）は、上部（t）と下部（b）を定義します（<ht> .. <hb>）。
    デフォルトは6（下）です。

    ベースレベルと組み合わせて使用する場合、このパラメーターはベースレベルからの適合階層を考慮しません。
    つまり、toc_depthとbaselevelの両方が3の場合、テーブルには最高レベルのみが表示されます。
    baselevelを3に設定し、toc_depthを "2-6"に設定すると、最初の見出しは<h3>になるため、目次に含まれます。
    この最初のレベルを除外するには、toc_depthを「4-6」に設定する必要があります。

ささいな例：

markdown.markdown(some_text, extensions=['toc'])
ページのトップへ戻る