注釈を貼れる記法の追加

[yumetodo]

cpprefjp/markdown_to_htmlの範疇になりそうだが、 cpprefjp/site#485 を書いていてQiitaにはある注釈を貼る機能がほしいと思った。

Markdown記法 チートシート - Qiita#注釈

[saki7]

これってCommonMarkのページ内リンクで書く方法ありませんでしたっけ

[yumetodo]

ざっと探した感じ<a name="foo"></a>したところに[](#foo)で飛ぶやつしか見当たりませんが、どういうやつのことでしょう？

[saki7]

見出しほげほげ

ああああああ　要出典

見出しほげ１

これは見出しほげ１です ¹

---

## 見出しほげほげ

ああああああ　[要出典]

## 見出しほげ１

これは見出しほげ１です [^1]

[要出典]:https://cpprefjp.github.io/
[^1]:https://cpprefjp.github.io/reference/vector/emplace_back.html

---

↑じゃダメですか？

Footnotes

1. https://cpprefjp.github.io/reference/vector/emplace_back.html ↩

[saki7]

cpprefjp/site@8dff49e これで注釈張ったので、これでよければcloseしていただけると。

[saki7]

あ、入れ子にするとうまく張れない。GitHubのプレビューだと張れてるのでこれはsite_generatorの問題かもしれない。

[saki7]

@melpon 今の https://github.com/cpprefjp/site/blob/055cb5f7cd1835883c6682aaa4489247fa7f707d/implementation.md のGitHub上のプレビューで表示されているのとまったく同じように本番でもリンクを張りたいのですが、本番でこれがうまく処理できていない原因とかに心当たりあったりしませんか……？

[yumetodo]

↑じゃダメですか？

それだと注釈に文章書けないような・・・

[melpon]

@saki7 今変換で使っている Markdown ライブラリは CommonMark ではないので…。
Markdown ライブラリの標準の Extension を見てみましたが、うまくやれそうな機能は特に無いみたいですねぇ…。

[yumetodo]

それだと注釈に文章書けないような・・・

ああ、結局aタグ使うと。それだと注釈で飛んだあと戻ってくるのを書くのが大変ではないかなと。

[yumetodo]

@melpon やはりこの辺の対応にはmarkdown-itへの移行が必要ですか・・・？pythonのコードいじってどうにかなるならそれでも構いませんが。

[melpon]

@yumetodo 自前で Markdown ライブラリの Extension を書くことになると思います。
ただ、CommonMark でない拡張に後々足を引っ張られそうな予感もあり、どうしようかなぁという感じですね。

[saki7]

@melpon ああ、なるほど。把握しました。

---

ちなみに、本件で直接の問題になっているのは、

[[^1]]

という入れ子のリンクにmarkdown_to_htmlのMarkdownパーサが対応してないということだと思います。

---

バックエンドのMarkdownパーサをCommonMark準拠のものに移行する場合は、Markdownの構文木に応じてcpprefjp拡張を適用している現行の処理を新しいパーサ向けに書き直せばよいので、基本的には難しくないと思います。作業量の問題だと思うので、余裕がある方がいればお願いしたいところです。

バックエンドのMarkdownライブラリを変更する場合は、 @melpon に意見を聞いてください。Pythonの流儀的にモダンであること、規格への準拠度が高いこと、構文木に応じた拡張が導入しやすいことなどが採用の条件です。

[saki7]

このIssueの本題の、「注釈を貼れる記法の追加」という点に関してですが、そういうものはCommonMarkには無さそうです。注釈記法をcpprefjpの拡張記法として導入することにはあまりメリットが見いだせないので、これはcloseします。

HTMLタグが直接書けるのはMarkdownの利点でもあるので、ここは <a name="#cite-12345"></a> の書き方で良いでしょう。色々なオープンソースソフトウェアのREADME.mdを見ていても、アンカーは大体そのようにして書かれていると思います。