Attribute Lists(属性リスト)

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

原文は

旧バージョンの記事は

【 目次 】

要約

Attribute Lists extensionは、マークダウンの出力でさまざまなHTML要素の属性を定義する構文を追加します。
このextensionは、標準のMarkdownライブラリに含まれています。

構文

基本的な構文は、MarukuのAttribute lists機能に触発されました(Webアーカイブを参照)。

リスト

属性リストの例は次のようになります。

{: #someid .someclass somekey='some value' }

ハッシュ(#)で始まる単語は、要素のIDを設定します。
ドット (.) で始まる単語が、要素に割り当てられたクラスのリストに追加されます。
キーと値のペア(somekey = 'some value')は、そのペアを要素に割り当てます。
ドット構文はクラスに追加されますが、キーと値のペアを使用すると、以前に定義された属性が常にオーバーライドされることに注意してください。

次のことを考慮してください。

{: #id1 .class1 id=id2 class="class2 class3" .class4 }

上記の例では、次の属性が定義されます。

id="id2" class="class2 class3 class4"

HTMLには、たとえばcheckedなど、一部の属性を単一の用語にするためのサポートが含まれています。
したがって、属性リスト{: checked }は、出力形式がhtmlの場合はchecked、出力形式がxhtmlの場合はchecked = "checked"になります。
中括弧は、属性リストとして識別されないようにバックスラッシュでエスケープできます。

\{ not an attribute list }

空または空白のみを含む中括弧の開閉は、エスケープされているかどうかに関係なく無視されます。
さらに、以下のような特定の場所にない属性リストは無視されます。
左中括弧の後のコロンはオプションですが、他の実装との一貫性を維持するためにサポートされています。
したがって、以下も有効な属性リストです。

{ #someid .someclass somekey='some value' }

さらに、開始ブレースの後と終了ブレースの前のスペースはオプションです。
読みやすさを向上させるために推奨されますが、必須ではありません。1

Attribute Lists extensionには、HTMLで有効なキーや値に関する知識がありません。
したがって、有効なキーと値が使用されていることを確認するのは、ドキュメントの作成者の責任です。
ただし、extensionは、キー内の無効な文字をアンダースコアに置き換えることでエスケープします。
複数の連続する無効な文字は、単一の下線に縮小されます。

ブロックレベル

ブロックレベル要素2の属性を定義するには、属性リストをブロックの最後の行に単独で定義する必要があります。

This is a paragraph.
{: #an_id .a_class }

上記の結果、次の出力が得られます。

<p id="an_id" class="a_class">This is a paragraph.</p>

例外はヘッダーです。ヘッダーは1行でのみ許可されるためです。

A setext style header {: #setext}
=================================

### A hash style header ### {: #hash }

上記の結果、次の出力が得られます。

<h1 id="setext">A setext style header</h1>
<h3 id="hash">A hash style header</h3>

関連項目

デフォルトでは、Fenced CodeBlocks extensionには属性リストの限定的なサポートが含まれています。 完全にサポートするには、両方の拡張機能を有効にする必要があります。

インライン

インライン要素の属性を定義するには、属性リストをインライン要素の直後に空白なしで定義する必要があります。

[link](http://example.com){: class="foo bar" title="Some title!" }

上記の結果、次の出力が得られます。

<p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p>

tables extensionが有効になっている場合、属性リストをテーブルセルに定義できます。
インライン要素の属性をそれを包含するセルの属性と区別するには、属性リストをコンテンツから少なくとも1つのスペースで区切って、セルコンテンツの最後に定義する必要があります。

| set on td    | set on em   |
|--------------|-------------|
| *a* { .foo } | *b*{ .foo } |

上記の例では、次の出力が得られます。

<table>
  <thead>
    <tr>
      <th>set on td</th>
      <th>set on em</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td class="foo"><em>a</em></td>
      <td><em class="foo">b</em></td>
    </tr>
  </tbody>
</table>

最初の列では、属性リストの前にスペースが付いていることに注意してください。
したがって、テーブルセル(<td>要素)に割り当てられます。
けれども、2番目の列では、属性リストの前にスペースはありません。
したがって、直前のインライン要素()に割り当てられます。
属性リストは、同じ方法でテーブルヘッダーセル(<th>要素)に定義することもできます。

制限事項

属性リストが機能しない要素にはいくつかの種類があります。
念のため、MarkdownはHTMLのサブセットであり、Markdownで表現できないものは、常に素のHTMLで直接表現できます。

Code Blocks:
コードブロックは、Markdown構文を表示できる必要があるという点で独特です。
したがって、属性リストがコードブロックの一部であるか、ラッピング要素の属性を定義することを目的としているかどうかを判断する方法はありません。
そのため、extensionはコードブロックを無視します。
コードブロックの属性を定義するために、codehiliteおよびfenced code blocksextensionにはいくつかのオプションがあります。
ネストされた要素:
Markdownは、他の要素内にさまざまなブロックレベルの要素をネストするためのメカニズムを提供します。
ただし、属性リストは直接の親にのみ適用されます。
属性リストをドキュメントツリーのいくつかのレベルに適用するように指定する方法はありません。
たとえば、blockquote3内に属性リストを含める場合、属性リストは、リストが定義されている段落にのみ適用されます。
blockquote要素自体に属性を定義する方法はありません。
暗黙の要素:
Markdownテキストでは表現されていない暗黙のさまざまなHTML要素があります。
たとえば、ul要素とol要素はMarkdownに存在しません。
それらは、リスト項目(li)の存在によってのみ暗示されます。
属性リストを使用して、ul、ol、dl、table、thead、tbody、trなどの暗黙の要素の属性を定義する方法はありません。

使い方

一般的なextensionの使用法については、extensionを参照してください。
extensionの名前としてattr_listを使用します。
このextensionは、特別な構成オプションを受け入れません。

ささいな例:

markdown.markdown(some_text, extensions=['attr_list'])

愚鈍人の独り言


  1. つまりコロンとブレースのとこの空白は無くても良いという事か。 

  2. 参考のためブロックレベル要素とインライン要素とその一覧を

  3. 引用・転載文であることを示すHTMLタグ