Footnotes(脚注)
《 初回公開:2022/03/26 , 最終更新:未 》
原文は
旧バージョンの記事は
【 目次 】
要約
Footnotes拡張機能は、Markdownドキュメントで脚注を定義するための構文を追加します。
この拡張機能は、標準のMarkdownライブラリに含まれています。
構文
Python-Markdownの脚注構文は、Markdownコミュニティ全体で一般的に受け入れられている構文に従い、PHP Markdown Extraの脚注の実装とほぼ正確に一致します。
唯一の違いは、出力にいくつかの微妙な点があります。
例:
Footnotes[^1] have a label[^@#$%] and the footnote's content.
[^1]: This is a footnote content.
[^@#$%]: A footnote on the label: "@#$%".
脚注ラベルはキャレット^で始まる必要があり、角かっこ[]の間にインラインテキスト(スペースを含む)を含めることができます。
最初のキャレットだけが特別な意味を持っています。
脚注の内容は、ラベルで始まり、その後にコロンと少なくとも1つのスペースが続く必要があります。
コンテンツを定義するために使用されるラベルは、本文で使用されるラベルと正確に一致する必要があります(大文字と小文字および空白を含む)。
その場合、コンテンツは同じ行または次の行のラベルの後に続きます。
コンテンツには、複数の行、段落、コードブロック、ブロッククォート、およびその他のほとんどのマークダウン構文が含まれる場合があります。
追加の行は、1レベル(4つのスペースまたは1つのタブ)インデントする必要があります。
複数のブロックを操作する場合は、コンテンツを定義するラベルとは別の行でコンテンツを開始すると役立つ場合があります。
このようにして、ブロック全体が一貫してインデントされ、作成者はエラーをより簡単に識別できます。
[^1]:
The first paragraph of the definition.
Paragraph two of the definition.
> A blockquote with
> multiple lines.
a code block
A final paragraph.
使い方
一般的な拡張機能の使用法については、拡張機能を参照してください。
拡張機能の名前としてfootnotesを使用します。
拡張機能の構成については、ライブラリリファレンスを参照してください。
出力を構成するために、次のオプションが提供されています。
- PLACE_MARKER:
脚注がレンダリングされる位置をマークするために使用されるテキスト文字列。
デフォルトは///Footnotes Go Here///
プレースマーカーのテキストがドキュメントに見つからない場合、脚注の定義は結果のHTMLドキュメントの最後に配置されます。 - UNIQUE_IDS:
reset()
への複数の呼び出し間の衝突を回避するかどうか。
デフォルトはFalse
です。 - BACKLINK_TEXT:
脚注の定義からドキュメント内の位置にリンクするテキスト文字列。
デフォルトは↩
(↩) - BACKLINK_TITLE:
脚注定義リンクのHTMLタグのtitle属性の値となるテキスト文字列。
%dは脚注番号に置き換えられます。
デフォルトはJump back to footnote %d in the text
- SEPARATOR:
脚注の区切り文字を設定するために使用されるテキスト文字列。
デフォルトは:
ささいな例:
markdown.markdown(some_text, extensions=['footnotes'])
インスタンス状態のリセット
脚注の定義は、クラスの複数の実行間のmarkdown.Markdownクラスインスタンス内に格納されます。
これにより、クラスが複数回呼び出された場合でも、すべての実行の脚注を一意のリンクと参照とともに出力に含めることができます。
ただし、必要に応じて、reset
を呼び出すことにより、実行の合間に定義をクリアできます。
たとえば、ブログのホームページに複数のドキュメントのコンテンツが含まれている場合があります。
reset
を呼び出さないことにより、すべての脚注がレンダリングされ、すべてに固有のリンクと参照があります。
一方、個々のブログ投稿ページには1つのドキュメントのコンテンツのみが必要な場合があり、そのページのみに関連する脚注を付ける必要があります。
実行の間にreset
を呼び出すことにより、最初のドキュメントの脚注定義は、2番目のドキュメントがレンダリングされる前にクリアされます。
reset
の呼び出し例:
md = markdown.Markdown(extensions=['footnotes'])
html1 = md.convert(text_with_footnote)
md.reset()
html2 = md.convert(text_without_footnote)