以前より公式サイトの写経に近いようなやつとかよく使うコマンドとかを書き残しておくサイトが欲しいと思っていました。

ブログでこういうことをやるのは難しいと思っていて、理由は記事の内容が玉石混合なのと、書きたいときに書きたいところに書くので情報がまとまっていないというのがあります。特に私のようになんでもかんでもブログに記録するような人間にはなおさらで、もっとサッと記録してサッと取り出せる。そういうサイトが欲しかったんです。で、ながらくDocusaurusのv2を待っていました。待っていたんですが、なんか一向に進捗が芳しくないので、別のもので構築することにしました。

こちらに作りました。VuePressで作ってます。

Fragments

以下、選定理由とかのやったことの記録的です。ただのやった記録です。

技術的な希望など


やるにあたって、下記が希望条件でした。

  • とりあえずカスタマイズとかしたくない
  • そのままつかいたい
  • とにかくそのままつかいたい
  • JavaScriptを触りたくない
  • CSSもやりたくない
  • とにかく簡単にやりたい
  • 全文検索できる
  • クロール拒否(noindex)できる
  • サイドバーがいい感じにできる
  • 断固絶対にいじりたくないし、ドキュメントも可能な限り読みたくない

結局ほとんどが満たせませんでした…

docsify


始めはdocsifyでやろうと思っていました。これはもうCDNからJavaScriptを読み込むだけでMarkdownからHTMLへのビルドも必要ない、生のMarkdownを放り込んでおくだけで表示してくれるという、しかも検索機能も付いてるとかいうやつです。凄くないですか?なので、これで始めてみたのですが、これ、メンテされてないんですね。いや、わかってたんですよ。メンテされてないのは。試す前から。自分もメインのサイトではないのでメンテされてなくてもいいか。と思って使い始めたのですが、やっぱり気になる。気になるのでやめることにしました。

Docute


次に試したのがDocuteで、これもdocsifyと同じアプローチです。こちらはかなりデザインもよく、すごく気に入りました。構築も楽です。こちらでいったんサイトの公開までもっていきました。できればこれで行きたかったです。しかし、下記の理由により止めました。

  • サイドバーがデフォルトで開きっぱなし
  • サイドバーが思った段組みにできない
    • これもあってこの後にVuePressを試しましたが、これは結局VuePressも同じでした
  • 検索実装が手間そう

というあたりです。そもそも、Markdownを事前にビルドしない(閲覧時にパースする)ということはコンテンツの量が増えれば間違いなくパフォーマンスが落ちるはずであり(これはdocsifyも同じはず)それであればもう結局静的サイトジェネレータの類でやるしかないかな。と思いました。

VuePress


最終的にVuePressを使うことにしました。VuePressを避けていたのはデフォルトのテーマが好みでないので、自分好みにするために弄らないといけないのが触る前から自明だったからです。後は、自分はフロントの人間ではないし、フロントのJavaScriptは必要最低限のレベルで抑えておきたいくらいの気持ちなので、このワールドオブJavaScriptみたいな思想があんまり好きじゃなくてとにかく避けてました。まあ、これはDocusaurusも一緒なんですが。

ここに差し掛かる前(Docuteの時点)でAWSのデプロイも組んでいたのですが(泥酔していたのも相まって)それもなかなかうまくいかずに「簡単にドキュメントを公開したいだけなのに5時間くらい消耗するとはどういうことだってばよ?」という気持ちで既にかなり消耗していました。そういう状況でVuePressを試したのですが「1,2,3で簡単にできますよ」みたいな書き方をしておいて、やっぱりゴリゴリドキュメント読まないと思い通りにできないし、ドキュメント読んでやっても思い通りにいかなかったし、開発モードと本番(ビルド後)で同じ結果にならないしでかなり消耗しました。Sincerely消耗。

以前はこういうのも面白いなぁとか思いながらやってたんですが、最近はもうこういうのがしんどい。自分はツールの使い方を覚えたいわけではなくて、とにかく、ゼロコンフィグで(自分好みの)綺麗な仕上がりのやつが、5分くらいでできて欲しいんですよ。「1,2,3で簡単にできますよ」は確かにそうなんですが、それはあくまでペライチのREADMEで立ち上げレベルの話で合って、それ以上やろうと思うと結局ドキュメントをそこそこ読まないとダメなので大変厳しい。実際かなり読んだし、VuePress本体のサイトの設定のコードとかも読んだ。わかってるよ。無理なのはわかってる。でも我々がやりたいのはJavaScriptを弄ることでもドキュメントを読むことでもないんですよ。ドキュメントをサクッと形にしたいんですよ。わかります??

結局、その後にVuePressで自分が思っていた構造に近いものを作るまででさらに数時間、レイアウトの修正とかをやってさらに数時間くらい使うことになってしまいました。

その上、そこまでやって立ち上げたサイトもサイドバーは結局予定していた構成で作るのが無理だったし、ローカル検索はh2,h3のみが対象だったりするし、テーマも公式のやつをコピーして弄りながらやったもののその公式テーマもCSSプリプロセッサにStylusが採用されているのですが.stylファイルとして切りだされているものと.vueファイル内の<style>タグ内にベタで書かれているものが大量にあり(しかも結構重複しているっぽい)どっちがどう効いているのかわからん上に、これを編集することによって開発モードと本番(ビルド後)で差分が発生する原因になってるっぽいし、大変厳しかった。なんかかなり愚痴のようなものになってしまって、VuePressの開発チームの人には本当に申し訳ないけどもっと簡単なものを期待していたので大変厳しかったです。まあ、最終的にいちおう予定していたものに近いのができたのでよかったかな。と思ってます。まだいくつも問題残ってるけど…。

なんでHexoでやらなかったのか


実際に始めるまではドキュメント系のフレームワークがもっとゼロコンフィグに近いものでできると思っていたのでHexo以外で始めたのですが、ここまで書いている通り思ったようにいかず、Hexoでやればサイドバーも全文検索の要件も自分の希望の条件は満たせるのはわかっていたので、途中でHexoでやろうかとおもいもしました。しかし、もともとブログ前提のフレームワークなのでドキュメント向けのテーマがあんまりないということと、やりかかって引き下がれなくなったので最終的にVuePressでやりました。

サイト名について


サイト名は構想時点ではnoteのつもりでした、しかし文章公開サービスのnoteと被るのを避けたかったのでCanvasで作り始めました。ドメインはyoshinorin.ioを取得したまま一切使っていないのがもったいなかったのでcanvas.yoshinorin.ioになる予定でした。ですが、AWSで公開する段階でfragments.yoshinorin.ioというS3バケットとサブドメインが作成されているのが発覚しまして、新規で作るよりこれを流用した方が楽なのとfragmentsの語感が好きなので使うことにしました。これらは当然自分で作ったのは間違いないのですが、なんのために作っていたのか思い出せないです。

コンテンツ


過去自分が勉強して書き残したやつとか順次移していきたいなと思います。要するにWikiです。記事にするまでもないものの集合体のようなWikiのような感じにするつもりです。もう雑多ですIT以外も載せるつもりです。このサイトの内のものでコマンド系の記事とかもそっちに移したいと思います。自分はあんまり公式サイトのコピーみたいな記事を書きたくないと思っているのですがmetanoindexを指定しており、検索には載らないはずなので公式サイトを自分向けにリライトしたようなものも書くつもりです。

あと、昔勉強したやつとかを漁ってたら2016年の初頭にTypeScriptを勉強した痕跡が残っていて「やるじゃん自分」と思った。まあ、今現在TypeScript全くわからないんですが…

感想


結局ツール系の簡単はあてにならなぁと思いました。当初の希望(ゼロコンフィグでドキュメント読みたくない&その他技術要件)はほとんど満たせませんでした。最終的にドキュメントをそこそこ読み込まないとダメだし、途中からもうOSSのWikiかなんかをサーバに立てた方が早くできる気もしたけど、サーバの管理と特にデータベースのバックアップをやりたくなくて、これも頑張ってその気持ちを抑えました。あとなんだかんだ言ってAWSのデプロイ系とかもめんどくさくて、これもVPSのnginxで配信した方が早くできると思ったけど、初回のみ立てれば後々メンテは楽と頑張って自分に言い聞かせながら構築しました。

ドキュメントの量が少なかったりネストが深くならないのであればDocuteで十分なのではないかと思いました。こちらもある程度ドキュメントを読む必要はありますが、VuePressの分量に比べればかなり少ないです。

まだレイアウト微妙なところも残ってるし、移したいコンテンツもあるので段階的に移していきたいです。