akabekobeko commented 3 years ago

33 対応。

既に remark-footnotes は組み込まれて処理もされていた。しかしドキュメント未掲載でテストコードがないため機能としてカウントされていないかった。これらを踏まえ改めて以下の対応を実施。

docs/vfm.md 記載
tests/footnotes.test.ts 追加
rehive-parse.ts で直に import せず footnotes.ts に切り出し
- 冗長だが src/ と tests/ の対応付けがわかりやすくなる
- オプションの知識を rehive-parse から隠蔽できる
- 万が一 handler と hast を処理したくなった場合の備え

@MurakamiShinyu docs/vfm.md についてレビューをお願いします。なお既存実装の inlineNotes: true をそのまま維持しているためインライン記法も対応されます。

akabekobeko commented 3 years ago

@MurakamiShinyu

33 での議論を踏まえて

remark-footnotes の機能をインラインも含めてそのまま利用
HTML を後工程で Pandoc 風に変換
Pandoc との差分
- 属性の順番、動作には影響ないはず
- 脚注側の <li> 内に <p> を入れない、remark-footnotes がこうしているのは <li> だけで十分だと判断してのことだと思われるため VFM でもそのまま踏襲

という対応をおこないました。レビューをお願いします。

MurakamiShinyu commented 3 years ago

基本的な動作はこれでOKだと思います。

テストしてひとつ気になったのは、見出しにインライン脚注がある場合です。

例:

# Hello World^[Footnote in a headng]

↓ vfmでの変換結果

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Hello WorldFootnote in a headng</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <section id="hello-worldfootnote-in-a-headng" class="level1">
      <h1>Hello World<a id="fnref1" href="#fn1" class="footnote-ref" role="doc-noteref"><sup>1</sup></a></h1>
    </section>
    <section class="footnotes" role="doc-endnotes">
      <hr>
      <ol>
        <li id="fn1" role="doc-endnote">Footnote in a headng<a href="#fnref1" class="footnote-back" role="doc-backlink">↩</a></li>
      </ol>
    </section>
  </body>
</html>

このHTMLの title 要素 <title>Hello WorldFootnote in a headng</title> にインライン脚注の内容が含まれてしまうのは望ましくありません。また、section の id 属性 id="hello-worldfootnote-in-a-headng" もインライン脚注の内容が含まれてしまいます。

（インラインではない脚注の場合をテストしてみると、脚注参照番号は title や id に含まれません。インライン脚注の場合だけこの問題があります。）

Pandoc での出力をテストしてみると、

$ pandoc --section-divs
# Hello World^[Footnote in a headng]
<section id="hello-world" class="level1">
<h1>Hello World<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a></h1>
</section>
<section class="footnotes" role="doc-endnotes">
<hr />
<ol>
<li id="fn1" role="doc-endnote"><p>Footnote in a headng<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
</ol>
</section>

Pandocには見出し内容を title 要素にコピーする機能が無いようなので、id についてだけの比較ですが、 id="hello-world" のようにインライン脚注の内容は含まれていません。

akabekobeko commented 3 years ago

調査メモ。

<h1> からの <title> 生成
- src/plugins/metadata.ts
- MDAST で最初に見つかった headeing の内容を mdast-util-to-string で文字列化
- remark プラグインではなく直に MDAST 操作しているため構文排他されない
- そのため記号類だけが除去されてインライン脚注の中身がそのまま引用される
<section> の id 生成
- remark-slug により heading の内容から id が生成される、この時点でインライン脚注の考慮なし
- src/pluguins/section.ts で heading の id が section に移動される
- これらの処理でインライン脚注の中身が小文字化されて id に引用される

akabekobeko commented 3 years ago

remark-slug の実装を見ると id 用の文字列は mdast-util-to-string と github-slugger を組み合わせて生成している。

よって Footnotes の HAST 処理時点で連番化をする際にこれらを利用して <title> と <section id="..."> にインライン脚注が引用された痕跡を判定、検出したら削除するようにすれば対策できるかもしれない。

akabekobeko commented 3 years ago

単に slug 処理などで判定された文字列を消すだけではダメで、例えば # Test^[Test] のように見出しとインライン脚注が同一になることも考慮する必要あり。

akabekobeko commented 3 years ago

<title> については MDAST で heading.children から一時的に type: 'footnote' を削除した状態でタイトルを生成、この後に children を復元することでインライン脚注とタイトルからの除外を両立させることができた。

remark-slag はサードパーティ製なので処理に介入できない。処理後の文字列から判定だと位置判定もしないと事故る可能性あり。ただし

実装が極小
依存 npm も github-slugger 以外は VFM と重複
remark プラグインではなく unified の transformer として実装されており remark 13 前後の影響を受けない

ことから移植して Footnotes 避けを実装してみる。ライセンスは MIT。TSDoc として移植版にはこれを記載する予定。

akabekobeko commented 3 years ago

@MurakamiShinyu 見出しにインライン脚注が定義されていると、それを元にした <title> と <section id="..."> に内容がコピーされる問題を修正してみました。確認をお願いします。

MurakamiShinyu commented 3 years ago

見出しにインライン脚注が定義されていると、それを元にした <title> と <section id="..."> に内容がコピーされる問題を修正してみました。確認をお願いします。

はい、確認しました。OKだと思います。

akabekobeko commented 3 years ago

@MurakamiShinyu 村上さんのチェックとコミットを受けてテストコード側もテキストと脚注リンク間に入れていたスペースを削除しました。ここまでの内容で問題なければ approve をお願いします。

vivliostyle / vfm

feat: footnotes #96

33 対応。

33 での議論を踏まえて