ドキュメントツールを作って学んでる

reStructuredText (rst) から Markdown (md) へ切り替えたことで、Sphinx から Rspress への移行を検討している。そこで Meilisearch から DuckDB Full Text Search (fts) を利用した全文検索の仕組みに切り替えるため、日本語全文検索を作り始めた。

一通り日本語全文検索を作り終えたが、検索とドキュメントって結構べったりなので、いい機会だからドキュメントツールもお試しで作ってみようということで作ってみた。最終的には Rspress にもどればいいという気軽な気持ち。

方針

基本的には Rspress を参考に docs ディレクトリ以下を SSG (Static Site Generation) として提供できる仕組み。ただし開発中は CSR (Client-Side Rendering) として変更点を気軽にを実現。

Rspress の _navi.json や _meta.json の仕組みはよくできてるのでマネしてもいいかなと思っている。index.md の仕組みも悪くなさそう。md ではな_index.json とかでもいいのでは？と思ったり。あと json じゃなくて jsonc が良いと思ってる。この辺りは色々試してみたい。

md

せっかくだし md のレンダリングも自分が見やすいように色々いじることにした。ただし Rspress は本当によくできていて、これを自分で作ろうとするのはかなり厳しいことがよくわかる。車輪の再開発をするのは本当に勉強になる。

shiki によるコードハイライト

コードハイライトは shiki を採用。とにかくキレイなのは良い。これは Rspress v2 が採用していたのでマネした。

Heading を md そのままに

次に Heading のレンダリング時に # を残す仕組みにしてみた。なんかフォントの大きさだけで段落を表現されても正直わかりにくい。

外部リンクのわかりやすさ強調

外部リンクの場合は明確にそれが外部リンクだよというのがわかる仕組みを追加した。小さな矢印を表示するようにしてみた。

md でのコピー と md URL 機能

表示知れてるページを md としてコピーする機能をつけた。これは今の時代に必須。また .html 部分を .md にするだけで md にアクセスできるようにした。これは Rspress の LLM plugin というので実現していたのでそれのマネ。

この .md はビルド時にコメントを削除する仕組みを入れようと考えている。ドキュメントには気軽にコメントを残したくなる。とはいえ rst とちがって md のコメントは書くのがめんどくさいので微妙だが。mdx だと楽なのかもしれない。

Heading にセクション番号を付ける

セクション番号を付けるはインターネッツでこんなの合ったら便利そう的なのを言っていただいたので、実装してみた。ただちょっと邪魔になるかもしれないのでデフォルトオフにした。この設定は OPFS とかに保存して永続化しておきたい。

折り返し (未実装)

また md のシンタックスハイライトで気になるのが横のバーが出るパターン。折り返しをなんとか読みやすく実現したい。折り返しが綺麗に表示できる md をあまり知らないので、まず調べるところから。

コードブロックの外だし (未実装)

code block にそのままコード書くとそのコード自体の検証ができないので、Sphinx ではできたコードを読み込ませる仕組みを実現したい。これは md にはない機能。ただ Rspress では実現していたので、マネしたい。

Alerts の見やすさ (実装中)

Markdown 拡張の Alerts (と呼ぶらしい) を見やすくしたい。

とりあえず適当に実装してみてる。

Rspress コンテナ (検討中)

:::note
This is a `block` of type `note`
:::

Rspress にある Markdown 拡張で Alerts っぽいけど、それより柔軟な仕組み。コンテナというらしく、これ便利そうなので対応したい。

多言語とマルチベージョン (検討中)

ここまで頑張るなら正直 Rspress 使った方がいい気がする。

DuckDB ファイル作成部分の Node 対応 (検討中)

今は md をうまいことやって、Lindera で分かち書きして DuckDB に保存して R2 へのアップロード部分は Python で実現しているのだが、Lindera-Wasm が Node で動かせると Node で完結するので良い。

未来

一通り実装して、プロトタイプから本番へデプロイできたらベクトル検索やリランカーなどを実装し、Claude Haiku を利用した RAG まで手を出してみたい。この辺りはパブリックに提供するのは難しいので、プライベートかつ Python での実装になると思う。

雑感

ドキュメントツールを作ってると世の中のドキュメントツールが良くできている事が本当にわかる。Sphinx は本当に素晴らしく、 ディレクティブという仕組みで好き放題拡張できるのはよかった。

ドキュメントツールは勉強がてら色々作ってみてはいるが採用するかどうかは悩み中。Rspress と時前の検索ツールだけになる可能性がある。

あと mdx もっとちゃんと勉強せねば ... という気持ちになってきている。