ドキュメントサイト生成ツールを Docute から別のものに移行すること

[MurakamiShinyu]

現在使用している Docute の問題点

• 参照: docs.vivliostyle.orgの問題点 #25 の「Docuteの問題点」

最大の問題点は、ウェブ検索で必要なドキュメントが見つからない（SEOに弱い）ということ。Docute のドキュメントの Comparisons でも、次のように、SEOが重要な場合にはDocute以外のものを勧めている：

VuePress / GitBook / Hexo

They all generate static HTML at build time, which is good for SEO.

If you care about SEO, you may like using presite to prerender your website.

Docuteからの移行先の検討

vivliostyle-sitegen が使えるようになるとよい。しかしすぐには無理そう。そこでそれまでほかのものを使うことを検討。

HonKit を調べてみた

参考記事：GitBookをForkしてHonKitを作りました

GitHubリポジトリ：https://github.com/honkit/honkit

公式サイト：https://honkit.netlify.app/

HonKit で作られたサイトや本の例

• Django Girls のチュートリアル - 多言語のドキュメントサイトの例
• JavaScript Primer - 迷わないための入門書 - 書籍にもなっているドキュメントサイトの例
  • GitHubリポジトリ https://github.com/asciidwango/js-primer をクローンして、ローカルでHonKitによるビルドができる。npm run build:all でwebサイトとPDF、EPUB、mobiが生成される。
  • 書籍版の『JavaScript Primer』は、HonKitで生成されるPDF（品質はよくない）とは違って、TeX (LaTeX)で組版されている。リポジトリ内に公開されている議事録から、書籍化のためにMarkdownからTeXへの変換や両方での修正のマージなどで手間がかかっていることがわかる（2019-10-07 書籍化の作業, 2020-03-13, 2023-02-16 など）。

HonKitをVivliostyle用に改造できるとよい

• MarkdownパーサーをVFMに変更
  • 現状のHonKitのMarkdownパーサーは、@honkit/markdown-legacyであり、kramed というライブラリが使われている。これについてHonKitにissueがある：
    • New markdown parser honkit/honkit#96
• PDF出力とEPUB出力をVivliostyle CLIに変更
  • 現状のHonKitのPDF出力とEPUB出力にはCalibre ebook-convertが

Astro はどう？

• GitHubリポジトリ：https://github.com/withastro/astro
• 公式サイト：https://astro.build/
• 参考になる同人誌：AstroとVivliostyleでWeb&出版物ハイブリッド開発
  • ソースのGitHubリポジトリ：https://github.com/spring-raining/vivliostyle
  • サンプルのGitHubリポジトリ：https://github.com/spring-raining/hello-astro-vivliostyle