vivliostyle.org、docs.vivliostyle.orgにおけるVFMのドッグフィーディングの進め方

[ogwata]

現在、vivliostyle.org は Jekyll を使い、docs.vivliostyle.org は Docute を使いMarkdownを処理しています。したがって、どちらのMarkdownもVFMとは違いがあります。

サイトを立ち上げたばかりの頃は仕方ありませんが、今の私達にはVivliostyle Flavored Markdown (VFM)があります。つい最近1.0をリリースしたこともあり、VFMの普及のためにも私達自身が積極的に使っていきたいところです。

vivliostyle.org、docs.vivliostyle.org におけるドッグフィーディングの進め方について討議したいと思います。皆さん、ぜひ知恵をお貸しください。

[ogwata]

現状、克服すべき課題をメモしておきます。

• Vivliostyleのサイトは、複数のリポジトリにまたがっており、且つMarkdownの記法も異なっている
  • vivliostyle.org→ Jekyll
  • Vivliostyle Docs→Docute
  • Vivliostyle Pub Docs→Docute
• 過去のコンテンツとの互換性確保が必要
  • 以前のコンテンツを修正加筆する際まで、全面的にVFMに書き換えが必要になるようなことは避けないといけない
  • つまり、現行の処理系を廃止にはできない（？）

[yamasy1549]

現在vivliostyle.orgはGitHub Pagesでビルドしており、そのおかげでローカル環境でビルドすることなくページを更新できています（たとえば、GitHub上でブログ記事を編集してそのまま投稿するなど）。

JekyllではカスタムMarkdownプロセスにより独自の記法をHTMLに変換することができます。この機能を使ってブログ記事などをVFMで書くことはできるはずですが、GitHub Pagesでビルドする際には使えないのでローカル環境でのビルドが必須になります。VFMをとるか、ローカル環境でのビルド不要をとるか、どちらかだと思います。

Vivliostyle.jsをCDNにして……という話が前にあったと思うのでそちらが使えるかもしれませんが、Jekyllとうまく併用できるかはちょっとわかりません。

[akabekobeko]

これを使えばいけるかもしれません。

• peaceiris/actions-gh-pages: GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.
• GitHub Actions による GitHub Pages への自動デプロイ - Qiita

GitHub Actions の workflow として VFM のビルドと actions-gh-pages 呼び出しによるデプロイを定義することになります。ビルドについては Static Site Generator 系のツールを単純化したようなプロジェクトを作成して実験するのがよさそうです。

[akabekobeko]

SSG 部分を参考にするなら GatsbyJS ですかね。私のブログはこれで構築して Netlify でホストしています。GatsbyJS を参考に最低限の機能を実装するとしたらこんな感じでしょうか。

• src/pages/ 配下の Markdown を VFM で public/ に HTML をビルドする
• src/pages/ 配下の Markdown からリンクされてるリポジトリー内ファイルを public/ にコピーする
  • 相対リンク対象だけをコピーする
  • 参考 akabekobeko/npm-gatsby-remark-copy-relative-linked-files
• src/static/ 配下の画像素材などを public/ にコピーする
  • 静的 CSS を置けばそのままコピーされる
  • CSS は src/scsss/ に SCSS を置いてそれを Transpile したものを public/ に出力でもよい

もしくは GatsbyJS の gatsby-transformer-remark だけを VFM に置き換えられれば GatsbyJS の知見とエコシステムをそのまま利用できてよいですね。

[ogwata]

@akabekobeko

ありがとうございます。
よく分かってないのですが、GitHub Actions + GatsbyJS でVFMを使えそう、ということでよろしいでしょうか。
その場合、上記の「過去のコンテンツとの互換性確保が必要 」という部分はどういう実装になるのでしょう？

[yamasy1549]

ref: vivliostyle/vivliostyle.org#101

[ogwata]

vivliostyle/vivliostyle.org#101 が作成され、そちらで本Issueが参照されているので、クローズしましょう。