docs.vivliostyle.orgの問題点

[ogwata]

• サイトの問題点

  • Vivliostyleの各ドキュメントの正式なURLと、Google検索で表示されるURLが異なる

    • たとえば、Create Bookの日本語ドキュメントの正式なURLは https://docs.vivliostyle.org/#/ja/create-book だが、「Create Book ドキュメント」でGoogle検索すると https://docs.vivliostyle.org/ja/create-book.html が出る。テキスト内容は同じだが画像が出ないなど問題がある。

  • サイト（https://github.com/vivliostyle/vivliostyle.org ）とドキュメントの制作システム（docs.vivliostyle.org）が統合されていない

    • 公式サイトのドキュメントページとは別にVivliostyle Viewer、Vivliostyle CLI、Create Bookのトップページが存在する
    • さらにそのトップページとは別にVivliostyle Pub Docs、及びVFM: Vivliostyle Flavored Markdown、Vivliostyle Themes、 vivliostyle-cli-helper-doc、それぞれのトップページがある
    • 公式サイトのドキュメントページには、上記のうちVivliostyle Pub Docs、vivliostyle-cli-helper-docへのリンクがない
• Docuteの問題点
  • JavaScriptファイルであってHTMLファイルではない（SEOに弱い？）
    • サイトの説明：Docute is basically a JavaScript file that fetches Markdown files and renders them as a single-page application.（Docute は基本的に、Markdown ファイルを取得して単一ページのアプリケーションとしてレンダリングする JavaScript ファイルです。）
  • 単一のサイトで複数のプロダクトのドキュメントを公開する前提なので、たとえば単一のプロダクトのドキュメントの場合、微妙に見出しがおかしくなる
    • たとえばVivliostyle Pub Docsでは、第1章が「最初にお読みください」
    • ところが左サイドのインデックスにはその表示があるが、本文のエリアにはない
  • H4相当以上の見出しが使えない（実質的にはH1〜H3相当まで）
  • （当然だが）VFMが使えない

開発者会議March 2024 #122 合意事項にもとづきまとめた。