Go to Qiita Advent Calendar 2024 Top
LoginSignup
5
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@domodomodomo

JavaScript で Markdown のライブラリを選定したい...

Last updated at Posted at 2024-03-24

書きなぐりです... まだ書きかけです... リンクとかぐちゃぐちゃです...

目次

  1. Markdown パーサ
  2. Markdown 方言
  3. サービス, SSG が採用しているパーサ
  4. ライブラリが採用しているパーサ
  5. 独自記法を定義することについて
  6. そのほか

1. Markdown パーサ

パーサ 方言
1 unified CommonMark のみ（GFM の拡張プラグインがあります）
2 marked CommonMark, GFM の全部を採用 *
3 markdown-it CommonMark, GFM の一部を採用 *
4 commonmark CommonMark のみ *
5 remarkable CommonMark, GFM の一部を採用 *
6 showdown Original のみ*(based on the original works by John Gruber)
補足: 方言の互換性について
  • CommonMark
    • unified と commonmark は双方共に CommonMark を「仕様」として採用していますが、双方の「実装」に互換性があるのか、unified と commonmark が実際に全く同じように Markdown -> HTML に変換するのかは調べてはいません。
  • GFM
  • リンク

npm trends

Screenshot from 2024-03-22 22-01-26.png

補足１: 比較 markdown と markdown-it と unified
  • 個人の感想です...
    • unified, marked, markdown-it の３つがメジャーかなという感じがします。
  • marked
    • 速度: 1 小さく変換速度が速い。markdown-it の２倍くらい速い。
    • 拡張: 3 反面、拡張性はそこまでで SSG や Qiita, Zenn といった大きなサービスでは採用されていない様子でした。
  • markdown-it
    • 速度: 2
    • 拡張: 2 拡張性がある。
  • unified
    • 速度: 3
    • 拡張: 1 拡張性がある。unified は mdx の仕様を策定しているからか markdown-it に比して React 系のライブラリ, SSG では広く採用されているように見えました。
  • Comparison Javascript Markdown Parsers
    • パーサがどう変換するか比較してくれます。
    • ページ右上に変換時間も表示されます。marked が一番早そうです。
    • unified がないのが残念...
  • remark
    • 上記ポストで言及されている remark は unified のラッパのようなものだと思っています。unified はプラグインを組み合わせて Markdown -> HTML のパーサを組み立てます。remark は unified 本体とそのプラグインを予め組み合わせた便利セットみたいなものだと思っています。

    • This package is a shortcut for unified().use(remarkParse).use(remarkStringify)
      https://www.npmjs.com/package/remark#when-should-i-use-this

補足２: commonmark
  • このパーサはあまり人気がないですが、メジャーな方言の１つである CommonMark の仕様が保存されているリポジトリにあったので記載しました。
補足３: unified
  • グラフについて
    • unified の用途は Markdown から HTML に変換するだけではなく、ほかにも用途があるそうです（詳しくはわかっていません）。
    • そのため unified ではなく unified のプラグインで検索したほうがより正確な値かもしれません（例えば remark-parse）。
    • 本稿ではいろいろややこしいので unified で統一しています。
  • unified の資料

界隈のつよつよの人たちが unified に肯定的なコメントをしている... でも具体的に何を指しているのか、どうしてよいのかわからない...orz

GitHub Star History

Screenshot from 2024-03-22 20-33-01.png

補足１: unified について
  • unified は GitHub Star History で検索すると npm trends に比べて極端に順位が落ちます。
  • これは恐らく開発者が unified を直接ダウンロードしているのではなく、ほかのライブラリやフレームワークを経由して unified をダウンロードしているため、直接見ることがないからではないかと思っています。
補足２: 比較方法について

ちょうど Express vs NestJS でどうやって比較するのがいいのか？みたいなのが話題にあがっていました...

2. Markdown 方言

# 方言 説明
1 Original Perl の実装、仕様。はじめて実装されたもの
2 CommonMark 仕様。方言が乱立したため標準化しようとしたもの
3 GFM 仕様。CommonMark を拡張したもの
4 MaltiMarkdown Perl の実装、仕様
5 PHP Markdown Extra PHP の実装、仕様
6 Pandoc Haskell の実装、仕様
補足
  • 個人の感想です。
    • Original, CommonMark, GitHub Flavored Markdown(GFM) の３つがメジャーかなという感じがします。
      • Original
        • 最初の方言です。その後さまざまな方言が乱立する。
      • CommonMark
        • という方言で標準化しようとする。
      • GitHub Flavored Markdown(GFM)
        • GitHub は CommonMark を拡張した GFM を使っている。という流れを抑えておくと良いかなと思いました。
  • 方言の一覧はどこから引っ張ってきたの？
    • RFC 7764 に記載されていました。
  • 文書の性格
    • RFC 7764
      • 一覧
    • RFC 7763
      • text/markdown という content-type 作りましょうねと提案
      • 厳密な仕様ではなくあくまでも参考資料のようなもの
      • This document is not an Internet Standards Track specification; it is published for informational purposes.
  • 方言
    • Original
      • Markdown.pl
      • RFC 7764 の一覧には Original の記載はありません。
      • Original の語の説明は RFC 7763 にあります。
      • 上記の表に Original があったほうが Original -> CommonMark -> GFM の流れがわかりやすいかなと思い追記しました。
      • Markdown の歴史、誕生 Original -> 乱立 -> 標準化 CommonMark の流れは英語版 Wikipedia に記述があります。
    • GFM
      • 本稿では GitHub Flavored Markdown を GFM と略すことにします。
      • GFM は CommonMark を拡張した仕様です。
      • GFM が CommonMark から拡張した部分の仕様は、以下のリンクのうち緑のマーカで引かれた箇所になります。
  • 方言とパーサ（仕様と実装）
    • GFM や CommonMark のように純粋に仕様として定義された方言もありますが、それ以外 MaltiMarkdown, PHP Markdown Extra, Pandoc は実装を元にして定義された方言なのかなと思いました。

3. サービス, SSG が採用しているパーサ

サービス パーサ 補足
1 Docsaurus mdx -> unified React 製の SSG, 技術ドキュメント向け
2 Nextra unified Next.js で使うライブラリ
3 Gatsby unified React 製の SSG
4 VitePress markdown-it Vue.js 製の SSG, 技術ドキュメント向け
5 Nuxt Content mdc -> unified Nuxt で使うライブラリ
6 Astro unified JavaScript 製 SSG
7 Sphinx markdown-it-py Python 製の SSG, 技術ドキュメント向け
8 MkDocs Markdown Python 製の SSG, 技術ドキュメント向け
9 Zenn markdown-it -
10 Qiita Qiita Marker Ruby 製
11 WordPress 調べてない PHP 製, CMS の巨人
補足
  • 一覧
  • SSG
    • JavaScript
      • React
        • Nextra
        • Docsaurus
        • Gatsby
      • Vue
        • Nuxt Content
        • VitePress
          • unified に比べると SSG やサービスで採用されていないように見えました。VitePress で採用されていました。VitePress が markdown-it を採用した理由は恐らく速度と拡張性と思われる。実際に速度を測ったわけではないです...
      • Astro
    • Python
      • Sphinx
        • 初リリース: 2008/03/21*
        • Python の開発ドキュメントを作る際に使用される SSG
        • markdown-it-py
      • MkDocs
        • 初リリース: 2014/01/24*
        • Python の開発ドキュメントを作る際に使用される SSG
        • Markdown
        • Original に準拠したライブラリがあったのは驚き...
    • サービス
      • Qiita と Zenn
      • Qiita, Zenn はなぜサーバサイドで markdown -> html の変換を行っているのか？音速で返ってきてびびった...
      • Qiita の markdown をそのまま Zenn に貼り付けても全然互換性がない... 結局、移植性みたいなのってあんまり気にしてもしかたないのかな...
      • 方言とかいうよりも、ライブラリの選定が重要になってくるのではないのか...
      • Qiita Marker
        • GMF 方言

https://x.com/azu_re/status/1772645677782409445?s=20

4. ライブラリが採用しているパーサ

  • React
  • React (Next.js に特化したもの)
    • @next/mdx ... local の MDX ファイルが対象です, hot reload が効きます
      • @mdx-js/loader ... Webpack を使って bundle しています
        • @mdx-js/mdx
          • unified
    • next-mdx-remote ... remote のファイルが対象です, hot reload は効きません
    • 上記２つのライブラリは Next.js の公式ドキュメントに使用方法の記載があります。
    • mdx-bundler
  • Vue.js
    • @nuxtjs/mdc ... Nuxt でなく Vue.js 単体でも使えます*
  • そのほか
    • Markdoc ... Stripe のドキュメント, 技術ドキュメントガチ勢が作ったライブラリ

Screenshot from 2024-03-23 08-10-52.png

Screenshot from 2024-03-23 08-08-06.png

補足１: なにを調べたの？
  • 上記に前節「3. サービスが採用しているパーサ」で挙げたものより低レイヤのライブラリを列挙しました。SSG やサービスに結びついていないライブラリ。
  • 3, 4 をまとめる方法が思いつかなかった。
  • 各 JavaScript フレームワークで定義したコンポーネントを組み込める Markdown パーサで分類しました。
  • 調べ方は package.json を掘り下げただけでソースコードをちゃんと読んで確認した訳ではありません。
補足２: 感想
  • npm trends では unified, remarked, markdown-it が３強のパーサだが、知名度の高いサービスやライブラリは marked を使ってない？
  • おそらく marked は小さい実装だから？拡張したりしないなら marked がいいのかな...
  • Vue.js の公式ドキュメントの最初の方にあるサンプルコードで marked が使われているのは見たことがある...
補足３:

5. 独自記法による拡張について

Zenn の生みの親である catnose さんは拡張記法を新たに定義することについては否定的なようです。

↓ ガチ勢は Qiita ↔ Zenn の方言のパーサを実装してしまう... でも自分にはこんな能力はない...

↓ ちょっと面倒みたいな意見も見る...

https://x.com/ubugeeei/status/1774069508258562550
https://x.com/ubugeeei/status/1774070092625801280
https://x.com/ubugeeei/status/1774072621547798933

6. そのほか

背景

  • どれが一番使われているパーサ、方言なのか知りたかった
  • 諸般の事情で SSG としてではなく SSR で mdx-next-remote を使っていて、なんか実装が重く感じた。こんなにコネコネしないといけないのかな？みたいなかんじで。これで良いのか、これが一般的なのか疑問だった。Next.js 使うなら一般的だと思った。でもなんか重い...orz

感想

  • 移植性を考えると Vue.js の template, React の JSX を使うよりも markdown の拡張記法を導入したほうがよい？
  • 拡張したいなって思って Markdown のパーサを調べたけど、拡張しないほうがよいみたいな気もしてきた...
  • 互換性がないから結局最初のライブラリの選定は大事なのかも...
  • 変換速度とかどうなんだろう...
  • commonmark.js で...
  • marked は大御所では採用されていないが変換速度は速い
  • 移植性みたいなことを考えると、いっそ独自の拡張記法は導入しない仕様のゆるふわな GFM も禁止して、 CommonMark + HTML タグだけってのもありなのではないのか...
  • あるいは WYSIWYG のエディタを提供して HTML で保存するみたいな？でもそうすると WYSIWYG のエディタにロックインされるのかな？
5
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
5
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?