UP
SmartyPants(属性リスト) 		前のページへ
Python-Markdown Extensionsのつたない翻訳 		次のページへ
WikiLinks

Table of Contents(目次)

初回公開：2018/01/01
最終更新：2018/01/13

「Table of Contents Extension — Python Markdown」をつたない翻訳，勝手な解釈。

【　目次　】

要約

Table of Contents extensionは、Markdown文書から目次を生成し、HTML文書に追加します。
このextensionは標準の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>
<h1 id="header-2">Header 2</h1>

ドキュメント内にマーカが存在するかどうかにかかわらず、目次はMarkdownクラスの属性（toc）として使用できます。
これにより、ページテンプレート内の他の場所に目次を挿入することができます。

例えば：

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

使い方

extensionの一般的な使用法については、Extensionsを参照、extensionの名前として markdown.extensions.tocを指定してください。
extensionの設定については、ライブラリリファレンスを参照してください。

出力を設定するには、次のオプションが用意されています。

  • marker: 目次を見つけて置き換えるためのテキスト。
    デフォルトは[TOC]。
    マーカーの検索を無効にするには、空の文字列に設定します。これにより、特に長いドキュメントで時間が節約されます。

  • title: 目次に挿入するタイトル。デフォルトはNone。

  • anchorlink: すべてのヘッダーを自分自身にリンクさせるには、Trueに設定します。デフォルトはFalseです。

  • permalink: 各ヘッダーの最後に永続リンクを生成するには、Trueまたは文字列に設定します。Sphinxスタイルシートに有益です。

    Trueに設定すると、リンクテキストとして段落記号（(¶ or "&para;")使用されます。
    文字列を設定すると、指定された文字列がリンクテキストとして使用されます。

  • baselevel: ヘッダーのベースレベル。デフォルトは1。

    このbaselevel設定では、ヘッダーレベルがHTMLテンプレートの階層内に収まるように自動的に調整されます。
    たとえば、ページのMarkdownテキストにレベル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つの引数をとる呼び出し可能なオブジェクト(関数)を定義して渡します。

    • value: slugifyな(HTMLのid属性にそのまま含めても問題ない)文字列.
    • separator: ワードセパレータ。

    呼び出し可能オブジェクトは、HTML id属性での使用に適した文字列を返す必要があります。

  • separator: ワード区切り文字。idの空白を置き換える文字。デフォルトは " -"です。

訳者による蛇足

slugify

slugifyという単語の意味がよくわからなかってので、以下を参考に訳してみたけど合ってるかな？

titleオプションを指定してみると

蛇足ながら、titleオプションの出力を以下のコードで確認してみた。

import markdown

makedown_text = u'''[TOC]

# Header 1

## Header 2
'''
print markdown.Markdown(extensions=[u"toc(title=目次)"]).convert(makedown_text)

実行結果

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

divタグ内の先頭にクラス属性がtoctitleのspanタグが追加されている。

ページのトップへ戻る