spec: Attributes on headings and other elements

[MurakamiShinyu]

Goals

For effective CSS styling, we need to add attributes on headings and other elements.

Prior Art

PHP Markdown Extra defines Special Attributes:

Special Attributes

With Markdown Extra, you can set the id and class attribute on certain elements using an attribute block. For instance, put the desired id prefixed by a hash inside curly brackets after the header at the end of the line, like this:

Header 1            {#header1}
========

## Header 2 ##      {#header2}

Then you can create links to different parts of the same document like this:

[Link back to header 1](#header1)

To add a class name, which can be used as a hook for a style sheet, use a dot like this:

## The Site ##    {.main}

You can also add custom attributes having simple values by specifying the attribute name, followed by an equal sign, followed by the value (which cannot contain spaces at this time):

## Le Site ##    {lang=fr}

The id, multiple class names, and other custom attributes can be combined by putting them all into the same special attribute block:

## Le Site ##    {.main .shine #the-site lang=fr}

At this time, special attribute blocks can be used with

• headers,
• fenced code blocks,
• links, and
• images.

…

Pandoc’s Markdown defines extensions for attributes, compatible with PHP Markdown Extra's Special Attributes and further extended:

• Headings
  • Extension: header_attributes
• Fenced code blocks
  • Extension: fenced_code_attributes
• Inline code
  • Extension: inline_code_attributes
• Links
  • Extension: link_attributes
• Fenced blocks
  • Extension: fenced_divs
• Inlines
  • Extension: bracketed_spans
  • Example: [This is *some text*]{.class key="val"}

Discussion

Related issues:

• spec: Fenced blocks
• spec: Auto generate HTML section elements
  • Generated <section> with attributes

[tk0miya]

It seems bracketed_spans conflicts with Ruby annotation (#10). Is it better to change syntax for Ruby?

[uetchy]

Yes we need to change the ruby ​​notation to fix the conflict.

The most likely notation is {Text|Ruby} https://github.com/vivliostyle/vfm/issues/10

[tk0miya]

Curly brackets are used in special attributes notation. So we need to make examples for it to avoid the conflicts with denden-markdown styled ruby notation.

How this text are parsed? An image and ruby-text? Or An image having special attributes? (Sorry for malicious example!)

![caption](uri){.Text|ドットテキスト}

[uetchy]

@tk0miya That's interesting. Can you provide some possible outcomes? so we can discuss more concisely. I think a properly implemented parser will fail to consume this as an image with attributed value because it has invalid character "|" for CSS class name.

[uetchy]

After reading this spec, I realized that "|" can be used for a part of CSS class name by adding "\" before "|" hence "\|" (seriously?) It means that we will have to put some limitations on this naming rule if we continue to adapt denden ruby syntax.

[tk0miya]

Actually, almost of users would not use to pipes to class name. So it is enough to define range of characters to special attribute block.

• A special attribute block can contain one or more attributes separated by spaces.
• An attribute should be element ID, class or attribute definition.
• An element ID should be starts with # and following one or more ASCII printable characters
  • In regexp, /^#[\x21-\x7e]+$/
• A class should be starts with . and following one or more ASCII printable characters
  • In regexp, /^\.[\x21-\x7e]+$/
• An attribute definition should be consist with attribute name, = and value
  • An attribute name and value should be one or more ASCII printable characters
  • In regexp, /^[\x21-\x7e]+=[\x21-\x7e]+$/
  • Quoted strings might be allowed as value (if needed)

[MurakamiShinyu]

現状の vfm での実装状況と課題

見出しその他の要素に属性を指定する記法は、現状の vfm (1.0.0-alpha.15) で一部は利用可能になってますが、Pandoc's Markdownで使える次のものがまだ使えません:

• Fenced code blocks

  • Extension: fenced_code_attributes

• Fenced blocks

  • Extension: fenced_divs

• Inlines

  • Extension: bracketed_spans
  • Example: [This is *some text*]{.class key="val"}

また次のものは、現状の vfm で利用可能ですが、課題があります。

• Headings
  • Extension: header_attributes

課題:

• spec: Auto generate HTML section elements #8 のコメント 現状の vfm と Pandoc --section-divs の動作の比較評価
• Attributes on headings not parsed properly when the heading ends with an inline element #46
• Pandoc の Heading identifiers にある以下の記法が未サポート
  • ## My heading ## {#foo}
  • Markdownでは見出しのあとに複数個の # を書くことができてそれらは無視されることになっている。そのあとに属性記法があるとき、現状の vfm では見出しのあとの # が無視されずそのまま出力されてしまう。
  • My other heading {#foo}
---------------
  • Setext-style (underlined) headings も vfm で使えるがその属性指定は未サポート
  • # My heading {-}
  • Pandocでは見出しの自動番号付けを特定の見出しでオフにするための "unnumbered" class が定義されており、その短縮記法として {-} が使える（{.unnumbered} と指定したのと同じ）。

• Links
  • Extension: link_attributes

課題: spec: <figure> for image container #15 に関して

• 属性が <img> タグに出力されるが、それを囲む <figure> タグには出力されない
  • <img> タグのみに意味がある属性以外は <figure> タグにも属性がコピーされるのがよいのでないか
  • id 属性は <figure> に移動したほうがよいのでないか

[akabekobeko]

@MurakamiShinyu

現状の vfm での実装状況と課題

について v1.0 対応とするか v2.0 へ見送るかの意見をお願いします。

[MurakamiShinyu]

について v1.0 対応とするか v2.0 へ見送るかの意見をお願いします。

v1.0は現状でリリースして、v2.0の検討・開発に進むのでよいだろうと思います。

[akabekobeko]

コメントありがとうございます。v2.0 へ送ります。