About

おはこんばんちは。 このサイトを作った Kuro Usada と申します。

好きなものはディズニー・プログラミング・食べることです!

なんて調子の自己紹介を長々書いても誰も読まないと思うので、あなたがこのサイトを見ている裏で何が起きているか、というポエムを代わりに書きます。

このサイトのrepoはgitlab.com/kurousada/siteです。

昔はみんな、そのサイトを作成した環境情報としてOSとかCPUとかがトップページやAboutページに書いてあったよねぇ…… あぁ、何もかもが懐かしい……

全体像

architecture
サイトの構成図

構成は gatsby + GitLab + Netlifyです。

記事の追加や編集はNetlify CMSを使い、そうでない部分はlocalで編集しgit pushします。

ドメインはFreenom、https化はNetlifyがLet's Encryptを使って上手くやってくれます。

記事を作成する時のフロー

個別の記事はmarkdownで書き、gatsbyという静的サイトジェネレータを使って変換し、レイアウトに埋め込んでいます。 記事一覧などもこの時に生成します。

このように内容と表現の分離を行うことで管理しやすくなり、新しい記事を書く時にも内容やタイトルに集中できるようになっています(集中してるとは言ってない)。

  1. ドラフトとしてNetlify CMSで記事を作成
  2. スマホやPCで内容を書く
  3. 内容をNetlify CMSにコピペ
  4. Netlify CMSでタグとか書く
  5. Publishすると勝手にgit pushしてビルドとデプロイしてくれる

Netlify CMSで編集しないのは、Netlify CMSが自動保存ではないため原稿書いてて何かの拍子に消えると悲しいからです。

Netlify CMSでは対応しきれない部分の編集フロー

Netlify CMSで対応しきれない部分(レイアウトやデザインなど)を編集する場合は以下のフローに沿って行っています。

  1. GitLabでIssue作る
  2. Issue毎にbranchを切る
  3. git pullしてlocalで編集する
  4. 編集し終わったらbranchをgit push
  5. masterにmergeして同時にIssueもclose

つまり普通の運用方法です。該当のbranchはmergeする時に消します。

なお、masterにpushするとあとはNetlifyが自動でビルドとデプロイしてくれます。 Netlify CMSの場合は記事を作成・更新した時点でmasterにpushされ、その後は同様です。

Issueの切り方

基本的にひとつの機能につき1つのIssueを切ります。

その際、EAHRフォーマットという勝手に決めたルールに沿ってIssueを書きます。

EAHRフォーマット

Issueを書く時に、以下の項目を順に書いていくフォーマットです。

  1. Expected - あるべき姿
  2. Actual - 現状
  3. How to achieve - 実現する方法
  4. Resources (optional) - 参考資料

Expectedでどういう機能にするべきかという要件やその機能が実装される重要性について書き、Actualで現状のバグやその再現法、機能がないことによる弊害を挙げます。

そしてHow to achieveでどのようにすればExpectedに出来るかという手順を示します。 この際に複数の方法が考えられる場合はそれぞれのPros & Cons(メリットとデメリット)を挙げ、比較します。

最後に参考資料がある場合はそのリンクを列挙します。

このフォーマットに沿うことで、実際にコードを書く前に問題と解決法について明確にでき、あとから見返した時に便利な「どうしてこのデザインチョイスとなったのか」という情報を残すことができます。

ちなみに、このフォーマットは英語ディベートのSQ/APやECMAScript proposalsのフォーマットなどを参考に作りました。

技術やサービスの選定基準

元々はHugo + GitHub + GitHub pagesという構成だったんですが、Netlifyが便利すぎて乗り換えました。

Netlify / Netlify CMS

もうね、すべてこいつのおかげです。 素晴らしいです。

gatsby

Hugoは自分が好きなGoで書かれてるし、速度的には素晴らしいんですが、如何せんテンプレートが弄りにくくて少し不便を感じていました。

Shortcodesとか キモイ ちょっとなぁ、って感じですし。 Themeは使いやすいけど。

というわけでHugoが殊更に悪いわけじゃないんですが、なんか痒いところに手が届かないことが重なったため、Netlifyに移行するタイミングでgatsbyに乗り換えました。

まあReact触ってみたかったしね? 今まではVueとWeb Components(Polymerは知らん程度だけど)しか知らなかったし……

結果的には弄りやすくなって嬉しい反面、やはり速度が気になるなあと言ったところ。

metalsmithもよさそうだったんだけど、あいつもNode.jsだから遅い上に、その時点ではNetlifyの公式サポートにHugoかgatsbyしかなかったので……

ジェネレータ部分はまだ模索中ですね。

GitLab

前はGitHubにrepo置いてGitHub pagesでホスティングしてました。

が、MSに買収されたことと、GitLabがOSSであること、それによって無料でローカルにもインストール出来ることなどを考慮し、GitLabに移りました。

とはいえサイト以外ではGitHubも使って(?)ますが……

ここもGitLab使ったことないから使ってみようかなって動機が大きいですね。

でもGitLabのが使いやすく思えてきたんで完全に移行してもいいかもなあ、なんて。

Markdown

これに関してはもう諦めですね 笑

というのも元々markdownには機能不足を感じていまして、例えば表のalignmentを制御出来ないとか、noteやinfoといったパーツがないとか、ToC(目次)を挿入できないとか……

で、以前からAsciidocを使おうと思ってたんですが、なんとHugoでAsciidocを変換しようとすると、ruby製のasciidoctorか、そのJS portであるasciidoctor.jsを使うため、とてつもなく遅くなるんですよ!

これじゃあ意味ないやん……って思ってHugoのgithub issues見てたら「asciidoctorをGoにportしよう」ってなってたんです。 わーい!と一瞬歓喜したものの、よく読むとそれが全然進んでないんですよ。

で、Netlifyに乗り換えるタイミングだったこともありgatsbyに乗り換えたんですが、案の定asciidoctor.jsは遅い。

その上、Asciidocの多種多様な機能に対応したcssを書くのはたるい。

テーマ使えって話ですが、そもそもAsciidocターゲットのテーマが少ない上にテーマを使っても結局カスタマイズするんだから、それなら最初から自分で書くわ!!ってなるんで。

というわけでとりあえずmarkdownで我慢して書きつつ、足りないところはHTML直書きすっか……となりました。

これなら将来asciidoctorが早くなった時にもpandasなりなんなりで原稿変換できるし、最悪Web Componentsが来れば足りない機能は自分でコンポーネント書きまくればいい話でしょ?

なおgatsbyはmarkdownを変換する時にReact Componentが書けるようにしてくれる、なんてことはないようでした……

Freenom

ドメインについて書くの忘れてた!

Freenomという無料でドメインを取得できるサービスを使いました。

でも2年目から継続する場合はお金かかるみたい……残念! でも継続せずに一旦解約して3ヶ月位するとまた無料で使えるようになるみたいですよ。 上手くできてますね!

出てきたやつら一覧

リンクをはるまでゆっくり待ってね!

おわりに

ここまで読むなんてありがとうございます。 余程暇なんですね。

暇ついでに他の記事も読んでってくださいよ? お願いしましたからね?ね?