Mimir Yokohamaに用語集機能

Mimir Yokohamaに用語集機能が追加された。

用語集機能はACCS(PureBuilderに取り込まれる以前の)やAki PHP Content Collection時代に実装されていた。

シンプルにACCSではJavaScript+Ruby/CGIで、本文エレメント(テキストノード)を探索し、文字列を送信してRubyで置き変えたものを返してもらい、innerHTMLを置き換える方式だった。

APCCでは単純に力技で置換えていた。

PureBuilderではこの機能を実現していなかった。 正確には一時期実装していたこともあるが、十分な質でなかったのだ。

そしてついに復活した用語集機能。

Pre Pluginsで処理することも考えたが、Post PluginsでRubyで処理している。

「辞書をワード長が長い順に並べ替えて|で結合し、正規表現としてコンパイルして置き換える」という手法はかつてのコードで考えたものである。

用語集のページも単純な手法でMarkdownを生成している。

で、今回もライブラリなしのPureJSで処理している。 今回は44行ほどだが、18行は共有化できるものなので、もう少し短くすることも可能だ。 DHTMLのお手本のような初歩的なものである。

Event.stopPropagation()Event.stopPropagationと書いて悩むはめになったけど。

PureBuilder Simply 1.4 リリース

PureBuilder Simplyの1.4をリリースした

特に大きな変更点は以下の通りだ。

  • HTML生成前に処理できるPre Pluginsに対応した
  • Pre Plugins/Post Pluginsで環境変数から文書メタデータにアクセスできるようになった

Pre PluginsはPandocにかける前のドキュメントを加工するものである。 Markdownと比べReSTは自由度が低いこと、それぞれのドキュメントフォーマットに基づいて処理しなければならないことから、新たに_docformatというメタ値が追加された。

今回のポイントはPre Pluginsであり、メタデータを渡す仕様は反映していなかっただけで、実は1.2時代からあった。

Pre Pluginsはおもしろいこと書いていないので、どちらかといえばメタデータ渡しの話をしよう。

これはPre Plugionsの一部である。 IO.popenはコマンド群の前に環境変数を置くことができる。 シェル的にいうと

みたいなことだ。

もちろん、同じような手法はRubyでも使えるけれど、ちょっとめんどくさい。IO.popenの利便性は簡便に損なわれてしまう。

かゆいところに手の続くRubyは、ちゃんとそのプロセス用に環境変数を渡す方法を用意してくれているわけだ。

予め環境変数にセットするのと何が違うのか。

まず、自身の環境変数としてセットすると、メモリーを2個分使う。

また、環境変数がそのプログラム自身の制御に影響するケースでは問題が生じる。

さらに、何度もプロセスを起動するたびにセットしてしまうと、ガベージコレクションの問題が出る可能性がある。

結局、子プロセスに対して伝播したいだけの環境変数はこのプロセスに対してのみセットするのが適切、ということになる。 シェルにおいても

ではなく、

あるいは

とすべきである。

PureBuilder Simplyのアップデート (ReST完全対応)

3ヶ月ぶりとなったPureBuilder Simplyのアップデート。

今回はMimir Yokohamaのウェブサイトの新連載(そもそも連載開始にお金かかるので時期未定)でReSTructured Textを使うため、ReSTに完全対応した。

完全対応のポイントは、従来きちんと対応できていなかったdocinfo(Bibliographic Elements)に対応するようにした。

ただし、これは「対応した」という言い方が適切なのかどうかわからない。 ひとつは、自力でdocinfoを解釈する部分が間違っていたのと、仕様の理解自体正しくなかったので適正にした。

File.open([dir, filename].join("/")) do |f|
    l = f.gets
-        if l =~ /:[A-Za-z]+: .*/ #docinfo
-          docinfo_lines = [l.chomp]
+        if l =~ /:([A-Za-z]+): (.*)/ #docinfo
+          frontmatter = { $1 => [$2.chomp] }
+          last_key = $1

        # Read docinfo
        while(l = f.gets)
            break if l =~ /^\s*$/ # End of docinfo
-            if l =~ /^\s+- / && (docinfo_lines.last.kind_of?(Array) || docinfo_lines.last =~ /^:.*?: +-/) # List items
-              if docinfo_lines.last.kind_of?(String)
-                docinfo_lines.last =~ /^:(.*?): +- *(.*)/
-                docinfo_lines[-1] = [ [$1, $2] ]
-              end
-              docinfo_lines.last[1].push(l.sub(/^\s+- +/).chomp)
-            elsif l =~ /^\s+/ # Continuous line
-              docinfo_lines.last << " " + $'.chomp
-            elsif l =~ /^:.*?: +.*/
-              docinfo_lines.push l.chomp
+            if l =~ /^\s+/ # Continuous line
+              docinfo_lines.last.push($'.chomp)
+            elsif l =~ /:([A-Za-z]+): (.*)/
+              frontmatter[$1] = [$2.chomp]
+              last_key = $1
            end
        end

-          # Convert Hash.
-          frontmatter = {}
-          docinfo_lines.each do |i|
-            if i.kind_of?(Array) #list
-              # Array element
-              frontmatter[i[0]] = i[1]
-            elsif i =~ /^:author: .*[,;]/ #author
-              # It work only pandoc style author (not Authors.)
-              author = i.sub(/:author: /, "")
-              if author.include?(";")
-                author = author.split(/ *; */)
-              elsif author.include?(",")
-                author = author.split(/ *, */)
-              end
+          # Treat docinfo lines
+          frontmatter.each do |k,v|
+            v = v.join(" ")
+            if((k == "author" || k == "authors") && v.include?(";")) # Multiple authors.
+              v = v.split(/\s*;\s*/)

-              frontmatter["author"] = author
-            elsif i =~ /^:(.*?): +(\d{4}-\d{2}-\d{2}[T ]\d{2}[0-9: T+-]*)$/ #datetime
-              key = $1
-              time = DateTime.parse($2)
-              frontmatter[key] = time
-            elsif i =~ /^:(.*?): +(\d{4}-\d{2}-\d{2}) *$/ #date
-              key = $1
-              time = Date.parse($2)
-              frontmatter[key] = time
-            elsif i =~ /^:(.*?): +/
-              key = $1
-              value = $'
-              frontmatter[key] = value
+            elsif k == "date" # Date?
+              # Datetime?
+              if v =~ /[0-2][0-9]:[0-6][0-9]/
+                v = DateTime.parse(v)
+              else
+                v = Date.parse(v)
+              end
+            else # Simple String.
+              nil # keep v
            end
+
+            frontmatter[k] = v
        end

    elsif l && l.chomp == ".." #YAML
        # Load ReST YAML that document begins comment and block is yaml.
+          @extra_meta_format = true # ReST + YAML is not supported by Pandoc.
        lines = []

        while(l = f.gets)

考え方自体に大きな変更があったため、変更行数も多い。 ただし、22165f2よりも8f6e453のほうが以前のバージョンとの違いは少なくなっている。

ここでひとつポイントだ。ReSTの仕様上、authorsa,b,cと書かれた場合は3人の著者になる。a,b,c;と書かれた場合は1人の著者になる。 だが、Pandocは;でのみ分割するので、この仕様に従っている。このため非常にシンプルな仕様だ。

基本的にdocinfoの場合、authorsdateのみが特別扱いされる。 Pandoc的にもそのような仕様になっており、authorsauthorの代わりに書ける点も正式な仕様に従っている。 PureBuilderもこれにならって、それ以外のフィールドについては特別扱いしない。 また、Pandocは仕様にない項目を入れてもエラーにしないため、この点も合わせてある。

この上で、メタデータの解釈はPandocに委ねることにした。 従来は-Mオプションを付加して上書きしていたのだが、解釈の違いからバグにもなったし、Pandocのほうが優秀なのでこのような挙動は取りやめた。

ただし、PureBuilder的にはこれではちょっと困る。 サイトの内容に関する情報をメタデータに記述する風習があるため、メタデータに書ける内容が決められてしまうのは困るのだ。

そこで従来サポートされていた「ReSTでも先頭をコメントにした場合はそのあとYAMLメタデータを書くものとする」という仕様も維持している。 この場合、Pandocは解釈できないため、@extra_meta_formatというインスタンス変数を追加し、これが真の場合のみ-Mオプションでのメタデータを使うことにした。

こうしてReSTも完全対応できることとなった。 asciidocも結構人気があるらしいのだけど、Pandocが入力にasciidocをサポートしていないのでサポートすることはできない。 Textileをサポートしてほしい人がいれば対応は考えなくもないけれど、私が知る限りPureBuilderでTextileを使いたい人はいないはずだ。1


  1. 比較的複雑な構造を書けることがPureBuilderの利点であり、また簡易な記述をしたい人にとってもMarkdownが困ることはないはずだからだ。Textileにはコメント機能があるため、サポートすること自体は不可能ではない。

Mimir Yokohama ウェブサイトの「タグ機能」の仕組み

Mimir Yokohamaのウェブサイトにこっそりとタグ機能が追加された。

だが、PureBuilder Simply自体にはタグ機能がない。 この実現方法は発想力勝負な部分があった。

ドキュメントにデータを持たせる

「記事情報」でも行われている方法として、Markdown YAML Frontmatter内に情報をもたせ、Pandocテンプレートで存在する場合だけエレメントを生成するような手法を取っている。

例えば帯域においては

というYAML Frontmatterが書かれている。 記事情報などは自動的に生成することができないため記事ごとにかかれており、若干執筆コストを上げている面もあるが、 なにしろMimir Yokohamaには力が入っているのでそれくらいどうということはない。 基本的なフォーマットをコピペしてしまえばそれほど難しくない部分でもある。

ちなみに、Pandocテンプレートで

$if(pickable)$
Something
$endif$

とした場合、pickable: no (つまりfalse)ならばここは生成されない。

この追加情報としてtagsが加わったのである。

問題は検索

タグを表示することは簡単だが、普通に考えればタグから同一タグの記事を辿りたいし、タグで検索もしたい。

単純な方法としてGoogleを使うこともできるのだが、それは必ずしもタグつきの記事が上位にくるわけではなく、思ったようには動作しない。 ちゃんと検索機能を用意する必要があったのだが、できればPureBuilder Simplyの枠組みの中で行いたいところである。

PureBuilder Simplyは原則として「MarkdownまたはReST文書から生成する」という前提になっており、 ACCSもindexデータベースからMarkdownドキュメントを生成し、このあとはPandocで処理している。

なのでPureBuilder Simplyの枠組みで処理するためにはMarkdownドキュメントを生成しなくてはいけない。

それなら全てのindexを探し回ってタグを集めればいいじゃない。

ARGV.eachしているので、全ての.indexes.rbmを指定すれば良い。 あとはpbsimply-pandocで処理できるが、タグに登場した.indexes.rbmは実際に記事が存在しているものではなく拾ってほしくないので消しておく。

.indexes.rbmとして書き出すようにした意図の一部に、このように外部からドキュメントデータにアクセスするというものがあった。

これによってドキュメント解析しなくてもメタデータを利用して機能拡張してページに含むことができる。

テンプレートにとうとう限界が

だいぶ魔改造されているPandocテンプレートだが、今回は限界が垣間見えた。

タグクラウドらしくエントリ数の多いタグを大きく表示したいのだが、Pandocテンプレートに計算機能や比較機能がなく、CSSにもないため、 Pandocテンプレートだけでは実現できない。MarkdownにHTMLを直接書くという方法はあるが(Markdown自体はRubyで生成しているため)。

また、URIエンコーディングをする方法はデータを二重に持たせる以外になく、それでもふたつの値を同時にとるイテレータがPandocテンプレートにないため、URIだけでURIエンコーディングをおこなう方法がない。

eRubyを使ってもいいのだが、できれば使いたくない。 現時点ではタグクラウドの大きさ分けはしておらず、URIもURIエンコーディングせずに使用している。

PureBuilder Simplyと新しいサイトのお話

PureBuilder Simply

デザイン

PureBuilder Simplyは従来とは大幅に考え方を変えた。

従来は基本的に「いっぺんの処理ですべて行う」というものであった。 このため、特に難しかったのが、ACCSにおける「前後の記事へのリンク」である。

PureBuilder Simplyは処理が分離されている。 一番基準となるスクリプトはデフォルトで全記事を処理する。 そして、全記事のメタデータをデータベースに書き出すのである。

従来はPureDocメタセクションに直接書くという方法をとってきた。 そのため、ドキュメントが処理時に変更されるのだが、これは扱いにくい側面が結構あった。

従来のPureBuilderはドキュメントごとに処理するようになっており、 メタデータはドキュメントにある。 そのため、処理時には「そのドキュメントのメタデータしか知らない」状態であった。

今回のPureBuilderもすべてのドキュメントのメタデータを読み込むことはしないが、 すべてのドキュメントのメタデータの書き出しは行う。

メインスクリプト以外については、このスクリプトが書き出したデータベースに基づいて処理を行うため、 すべてのドキュメントのメタデータを知った状態で処理することができる。

Frontmatter

もともとPureBuilderはPureDocを前提としていて、Markdown supportはPureBuilder2で採用された。

Markdown Supportを採用したのはWindowser向けのフレンドリーシュガーであり、 Mimir Yokohamaでサービスを展開するにあたって、記述の難しいPureDocではなく、 記述しやすいMarkdownで書けるようにすることで「ユーザーによる更新の容易さ」を向上させる目的があった。

この時点でMarkdown YAML Frontmatterのことを知らなかった。 そのため、従来のPureBuilderではMarkdownドキュメント中にHTMLコメントを入れ、その中にPureDoc meta headerを入れるという仕様になっていた。

だが、そもそもMarkdownにYAMLでメタデータを書ける仕様である。 同じYAMLのメタデータなのだから、これに従うべきだ。

そのため、PureBuilder SimplyではMarkdownドキュメントのFrontmatterを必須としており、 frontmatterが存在する前提で処理する。 (titleメタデータが必須であるため、どのみちfrontmatterは必須となる)

さらにReStructured Textに対応したが、これも先頭にコメントを入れてYAMLでヘッダを書く、という仕様とした。 次のような具合である。

ReSTなら

Pandoc

PureBuilder Simplyはドキュメント処理をPandocにゆだねている。

これは別に手抜きというわけではない。従来にしてもMarkdownの処理はKramdownによって行っているのであり、 PureDocの実装は別なので特にPandoc採用でアウトソーシングしたという感はない。

Pandocの利便性と「標準性」から、「Pandocを主としてPureBuilderは補助であるほうがユーザービリティが高い」と判断したのだ。

PureBuilder Refinedでは新しいPureDoc Zをサポートする予定だが、 PureBuilder Refined自体がPureBuilder Simplyでは不足の場合に限られるので微妙かもしれない。

「事前生成」戦略

PureBuilderは言葉の意味としてはCMSで合っているのだが、どちらかというとCCS(Content construction system)に近い。 基本的に生成機能だけで、管理に関してはシステムの標準的機能でなるべく簡単てにできるようにしている。

一般的なCMSとの最大の違いは、「Webアプリケーションとして動作しない」ということだろう。 原則としてPureBuilderは(ホームページビルダーなどで書いた場合と同様に)ローカル環境でウェブページを組み上げ、そのままアップロードすることで動作する。

従来のPureBuilderにあった、Webアプリケーションとして動的に生成するためのプラガブルな仕様は現時点ではPureBuilder Simplyにはない。 予定もされていない。単一ページのサポートは限定的で、原則としてディレクトリ単位でビルドを行う。 全体ビルド機能も排除された。

より「サイトを構築するためのスクリプト」という点に特化した。

私のウェブコンテンツ生成は可能な限り「事前生成戦略」をとっている。 通常、ページは書く回数よりも読まれる回数が多いので、コストのかかる処理は1度だけ行いたい、という方式だ。

これは構造的に最速の方式でもある。

ウェブサイトの仕組みを考えればわかるが、たとえばWordPressでは

  1. ウェブサーバーが接続を受け付ける
  2. ウェブサーバーがPHPプロセスにWordPressを渡す
  3. WordPressがデータベースにアクセスする
  4. データベースから必要なデータを受け取ったWordPressがページを生成して返す
  5. ウェブサーバーが応答する

という手順になる。 WordPressのキャッシュ機能ではWordPressはデータベースから受け取った結果を処理せずにそのまま応答するため、高速化するのだが、 それでもこの接続にかかる時間が決して小さくない。

対して、静的ファイルならば

  1. ウェブサーバーが接続を受け付ける
  2. ウェブサーバーがファイルを読み込んで応答する

とプロセスが少なくなり、より高速だ。 WordPressの高速化手法も、PureBuilderが同様の手法を適用すればさらに高速する。

さらに、ウェブサーバーにとって静的ファイルの応答は基本的機能であるため、 より高速なウェブサーバーが選択できる、というメリットがある1

また、静的ファイルのみでウェブサイトの構築が可能なことで、ウェブサーバーの選択肢が増える。 PHPが動作しないGeocitiesやGitHub Pagesでも構築可能だ。

Mimir Yokohama新サイト

新サイト開設

Mimir Yokohamaの新ウェブサイト開設は、主に「異様にサイトが重くなっている」という事情からきているのだが、 実はそもそもPureBuilder Simplyはこの新サイト構築のために書き直した。

Aki SIE新サイト開設時もそのためにPureBuilder2を作ったのだが、 PureBuilder2が6ヶ月も要したのに対して、作業時間で4日、経過時間でも9日と非常に速く書き上がった。 やはりデザインは大事だ。

そして当然ながら、Mimir YokohamaウェブサイトがPureBuilder Simplyのデビュー戦となった。

「楽」という言葉の意味

Mimir Yokohamaのウェブサイトの出来には非常に満足している。

だが、この開発において“PureBuilder Simplyの開発”は全行程における30%程度でしかなかった。

PureBuilder Simplyを使ったサイトは非常に「楽」であり、「簡単」なのだが、誤解してはいけない部分がある。

今回はWordPressからの移行であるため、WordPressで利用している機能に近い状態を狙った。 デザイン的にも近く、バックエンドの変更や、それによって品質が低下した印象を与えないようにしている。

まず言っておくと、「WordPressのサイトを欲している」のであれば、PureBuilderを採用するよりも、 WordPressを採用したほうが確実に楽にできる。 なぜならば、そもそも欲しているのはWordPressなのだから、WordPressよりも楽にはならない。

そもそもPureBuilder Simplyによる構築と、WordPressによる構築はちょっと話が違うのだ。

WordPressの場合、テーマ機能やプラグインなどは既に揃っている段階から話をはじめる。 PureBuilder SimplyはそもそもWordPressではできない完全なカスタマイズを実現するという前提があり、 WordPressで言えばテーマやプラグイン、CSSなどを「すべて0から記述するところからはじめる」というのと同じ位置にある。

もしもWordPressをその位置ではじめるという形で条件を揃えたならば、PureBuilder Simplyのほうが「楽だ」と断言できる。

実際はそのような条件では比べないと思うのだが、逆にWordPressに合わせて構造やビルドの仕組み、テンプレートやCSSなどがすべて揃った状態からはじめるならば、 これもPureBuilderとしてはそこまで分の悪い勝負ではない。

なぜならばその状態で必要なことは

  • 文書を配置したい場所に新しくファイルを作り、MarkdownまたはReSTで書く
  • PureBuilderのバッチスクリプトを実行する
  • Gitでcommit&pushする

というだけのことだからだ。

「設定ファイルを書く」「コマンドを実行する」というあたりに、「Unixer的な楽さ」の感覚があるが、 これに関しても別にお客様に納品するときにはちょちょいと調整すれば良い話だ。 若干手順が多いようにも感じられるが、実際はWordPressの場合は

  • ログインページにアクセスしてログインする
  • ダッシュボードから新規記事の投稿を選択する
  • ページ上で文章を書き、タイトルやカテゴリなどを選択する
  • 投稿ボタンを押す

という手順で、慣れてしまえば麻痺するが、かなり手順は多い。 私が使っているWordPressサーバーは遅く、1クリックあたり1分とか待たされるので、 「WordPressは手順が多くて面倒」という印象が強い。 あちこち飛んではキーボードとマウスを持ち帰るUIも嫌いだ。

もし、PureBuilder Simplyでできることと相当のものとして、 「WordPressもデザインや挙動をカスタマイズする」 という条件にしたならば、これはPureBuilder Simplyが有利だろう。

PureBuilder Simplyを採用するのは「入り口」

だが、実際はPureBuilder Simplyの採用というのは全行程においてそこまで大きなものではない。 おそらく、PureBuilder Simplyのデフォルトで作られたサイトには誰もが失望するだろう。

PureBuilder Simplyの場合、「テンプレート」と「CSS」という要素がある。 これを書くのは、PureBuilder Simplyで「簡単にしている」部分ではないところであり、技術者の腕のみせどころだ。

最近はwebといってもCMSありきのエンジニアが増えていて、HTMLやCSSを直接記述することができない人が増えている。 だが、それはCMSの枠の中でしか仕事ができていない。 PureBuilder Simplyはそれをイチから作るのであり、ウェブデザイナーとエンジニアの腕の見せ所だ。

PureBuilder SimplyのテンプレートはPandocのHTMLテンプレートである。 ただし、「Pandocの出力に対してeRubyで処理できる」ようになっている。 結果、テンプレートの展開は2度行われる。

Pandocのテンプレート機能は意外なほど強力だが、 「値が○○だったら」という式はかけない。

eRubyは完全なプログラムであり、「なんでもあり」である。

比較的単純な(PHPやSSLで行うような)ものに関してはPandocテンプレートで処理できる。 実際、現時点でMimir YokohamaのウェブサイトはeRubyでの処理を無効にしている。

PureBuilder Simplyにおけるテンプレートの作成は「若干の、もしくは本格的なロジックを含むHTMLテンプレートを書く」という作業である。 もちろん、それはデザインが必要であり、CSSと連動した「ページ設計」が必要となる。 ページ設計はかなりエンジニアリングレベルの高い作業だし、 最も単純にはデフォルトテンプレートを使っても良いのだが

CSSと連動した高度なロジックを使いたいといった場合には難易度は上がる。

プログラミングではないけれど、ロジカルに考える

もちろん、CSSを書くのはプログラミングに近い次元になってくる場合もある。

今回のMimir YokohamaのウェブサイトはハンバーガーメニューとドロワーについてはJavaScriptを一切使用していない。 これはAki SIEウェブサイトで使用されていたものの改善版である。

だがそのために、配置や仕組みに関してはかなりロジックが含まれている。 CSSにはロジックはほとんど含まれないが、「ロジックをほとんど含むことのできないものによって動的なフローを実現する方法」を考えるところにロジックが行使されているのだ。

プロモーションモードのページでは下からフェードインするようなページデザインになっているが、 これもJavaScriptは使用していない。

これは単純にHTMLとCSSで実現するウェブサイトを構築するときに、 「単に書くのではなく、そこにロジックを含んだ構造をもたせる」ときに必要となるものだ。

PureBuilder Simplyはウェブサイト構築ツールであって、 デザインに関しては感知しない。 だから、そこに関しては「自分で作る」必要があるのだ。

今回も難易度や作業量としては、テンプレートとCSSを書くことのほうが大きかった。

PureBuilderはサイトの内容については感知しないのだから、別にJavaScriptを含んでもいい。 特にそれを禁止はしていないし、支援もしていない。 別にWordPressのクローンを作ることも、できなくはないのだ。

「サイトを構築する」手間で考えると…

単純に「見栄えするサイトを作りたい」という条件で考えた場合、 WordPressのほうがずっと楽だ。 なぜならば、デザインやロジックが既に存在していて、それを選ぶだけだからだ。

PureBuilderが担っている部分に関してはWordPressよりも楽かもしれないが、 WordPressにはあるがPureBuilderにはない部分がある。 それについてはどうしてもWordPressでは発生しない労力を払わざるをえない。

だから、サイトを構築する手間がWordPressよりも軽いということはない。 WordPressのインストールの労力を含めてもだ。

だが、そのような「敷居の低さ」を求める人がPureBuilder Simplyを自らインストールしてサイトを構築することは想定していない。 PureBuilder Simplyで自ら構築する人は、そんなものがなかったとしてもテンプレートを書き、CSSを書き、JavaScriptを書く人だ。 私がお客様にPureBuilderの簡便性を説くときは、そのような想定で話しているわけではない。 構築はこちらで行って、更新をお客様がされる際には難しくない、ということを言っているのだ。

テンプレートやCSSやJavaScriptは自分で書く、という前提のもとでは、PureBuilder Simplyの採用はかなり労力を削減することができる。 PureBuilder2と比べ管理の手間もかなり減り、非常に楽になった。

新サイトのデザイン、ポリシー

PureBuilderの強みは事前生成による高速性である。

さらにMimir Yokohamaでもポリシーとしている「軽量さ」と「アクセシビリティ」に重きをおいたデザインとなっている。

ただし、Aki SIEのウェブサイトは発想力をアピールする意図もあったのだが、デザインがちょっと古くさい2。 今回Mimir Yokohamaのサイトではよりモダンなデザインを採用することにした。

といっても、そのデザインはほとんどがWordPressで使用していたテーマのビジュアルを踏襲している。 ただし、全く同じというわけではなく、もとがシンプルなデザインであったために「ブロックごとに端までボーダーをひっぱる」「白に対してグレーのラインを引くモノトーン調」「右側サイドバーの2カラム」といったことを踏襲しているだけで、 メニューデザインなどは異なるし、実はカラーテーマも違う。 このあたりは「変えることが目的だった」わけではなく、そもそももとのブログでもカスタマイズしたかった部分なのだ。

ちなみに、ブログではそんなシンプルなデザインであるにもかかわらず、ちょっと古い環境(IEなど)では表示が崩れる。 なんでその程度のもので崩れてしまうのか、私には疑問でならない。

前述の通り、ハンバーガーメニューやフェードインテキストなどはCSSで記述されている。 これは、主に次のような意図だ。

  • JavaScript禁止の環境や、JavaScriptを搭載しないブラウザでもエクスペリエンスを損ねない
  • JavaScriptを使用していない分容量的に軽量
  • HTMLを「意味」を欠落させない

ただし、古いブラウザでのエクスペリエンスは若干犠牲になっている。 だが、それは「アニメーションが表示されない」程度の話で、表示自体はChrome 1.0, Firefox 1.7, Opera 9.0, Safari 3.1で対応している。 あまり言いたくはないが、IEは9.0からの対応だ。

実は今回のサイトではHTML中に同じメニューが2回登場する。これは、上記環境よりも古い環境においてはドロワーが表示できない代わりにサイドバーにメニューを表示させるようにするためだ。 これはアクセシビリティのための処置だが、場合によっては1kB程度はサイズが増加するため、ちょっと残念なところだ。 このメニューはごく初期のCSSしかサポートしない環境でも正常に表示される。 CSSを全くサポートしない環境の場合、メニューは2つ表示される。 この場合上のメニューは記事タイトルよりも上になり、高さもあるため見栄えしないが、そのような環境では仕方ないし、十分許容範囲だろう。 むしろタイトルと記事の間に入るよりはずっと良いと考えられる。

軽量性重視だが、従来と違い飾りとしての画像がところどころに入っている。 従来があまりにも殺風景すぎたという反省であり、このあたりはブログの時点で投入しているものを継承している。

プロモーションページの実現

全く印象の異なるプロモーションページだが、書き方はほとんど同じである。 別にテンプレートをかき分けることもしていないし、普通にMarkdownで書かれたページだ。

プロモーションページの印象の違いは、テンプレートにおける若干の工夫と、CSSによって実現されている。 frontmatterでプロモーションページであることを指定すると、Pandocテンプレートによってそれがクラス設定される。 あとはそのクラス設定に基づいてCSSで見せたくない要素を消去し、一部レイアウトを変更する。

こうした発想力は、やっぱりロジカルシンキングなのだ。

プロモーションページもかなりシンプルだが、 見出しには画像を使いたかった、という気持ちがある。

そうしていないのは、「適切な画像」の選定が非常に困難だったことと、 ヘッダーごとに画像を選択するためにはそれなりにあまりスマートでない余計なロジックを追加する必要があったからだ。

もしもこれぞという画像があれば採用することだろう。

ちなみに、プロモーションページはスマートフォンの商品プロモーションページをイメージしている。 なるべく説明的にならないようにしたのだが、後に書いたものほど説明的になってしまった。 どこまでイメージで語り、どこまで具体的に語るかは難しいところだ。

速度

実際のところ、Mimir Yokohamaにおける制作ポリシーと同一ポリシーで制作したのであり、「最速を目指す」という方式ではない。3

だがそれでも、旧WordPressサイトの10倍程度の速度になっている。 高速化のために使用した手段は以下のようなものだ

高速なサーバーを選択
ConoHaはSSDを採用しており、ネットワーク帯域も太く高速だ。 Nginxを採用
静的ファイルの応答に関してはNginxは最速に近い コンパクトなHTML
できるだけ冗長な表現を避けてコンパクトなHTMLが生成されるようにした。ただし、アクセシビリティを優先してメニューは重複している 可能な限りCSS
JavaScriptなしで動作するようにしたのは「JavaScript無効というオプションを与えるため」だが、ロジックの最適化によってある程度の容量削減に繋がっている WebP
WebPをサポートするのはChrome/Chromium系列だけだが、WebPは「アルファチャンネルつきロッシー圧縮」が可能なため、PNGよりもだいぶ軽くなる。一部PNG画像についてはobjectタグによりWebPを優先して使用するようにしている。アクセシビリティを重視し、重要な画像ではこの処理は行われずimg画像を使用している。 画像よりもCSS
「デザインはセンスでがんばる」方式で、画像などのアイテムの使用数は非常に少ない。寂しさはグラデーションで埋めているが、華やかさに欠ける感は否めない。

高速性ということでいえば、「CSSが重い」ということは感じるが、改善は若干難しい。 もちろん、minifyなどのテクニックである程度は小さくなるが、保守性を重視しているためだ。

また、CSSを3つから1つに減らすというアイディアもあったのだが、比較的サイズの大きいファイルであり、並列ダウンロードしてもらったほうが速いことから分割に戻した。

ミーミルのロゴなどは埋め込んだほうが高速化するだろうが、軽量化には寄与しないし、アクセシビリティが下がるので実施していない。 トップページで51.5KB、低速なうちの環境でTTFBは14.08ms、DNS lookupとfaviconを除いた時間は101.36msとなった。 従来が500kB/5s程度だったことを考えると、この計測では1/10の容量、50倍の高速化となっている。

MarkdownとReST

今回、Pandocの採用によってMarkdown以外のソースフォーマットに対応することが可能になった。 そして、最初に採用したのがReStructured Text(ReST)である。

Pandocがサポートする中で最もMarkdownに近い汎用性があるのはReSTである。 他にそのようなフォーマットはないが、あるいは専門分野での記述用にDocBookなどをサポートする可能性はある。

なお、入力ソースとしてのHTMLは、判別しがたさの観点からサポートは行わない。

ReSTはMarkdownと比べて表現力に優れている。 記述の簡便性も「好みの問題」と言えるような差異だ。 ただし、ReSTが優れている点について必ずしもそのまま適用できるわけではない。 なぜならばPandocがReSTをフルサポートしていないからだ。

実際のところ他フォーマットへの変換を想定しないのであれば、HTMLを直接記述できるMarkdownの優位性は揺らがない。


  1. 今回はNginxを使ったが、基本的にNginxも静的HTMLファイル向けのサーバーで、アプリケーションは他のサーバーに接続するリバースプロキシとして動作する方式だ。Thinなどを使う手もあるかもしれないが、Nginxよりも高速化するかは疑問。

  2. 800pxのブロックが中央にフロートしているデザインは2005年ころから流行したブログデザインと類似のものだ。今でもamebloなんかはこのデザインなのだが、新規にサイト立ち上げると画面めいっぱいまで使うデザインがデフォルトになっている。

  3. 最速を目指すのであればコードゴルフやminified、画像の排除や機能の統一化なども考えられる。実際のところ「速度は上がるがアクセシビリティが下がる」方式は取ってないし、コスト過剰にもならないようにしている。

ConoHaへのサーバー引っ越しレジュメ (DeleGate-Nginx/Postfix/Dovecot, Let’s Encrypt)

概要

作業概要は以下の通りだ

  • サーバーをDTI(@ServerMan)からConoHaに変更する
  • サーバーOSをCentOS (6.9)からArch Linuxに変更する
  • WebサーバーをDeleGateからNginxに変更する
  • WebコンテンツシステムをPureBuilder2からPureBuilder Simplyに変更する
  • Mimir YokohamaのWebコンテンツを別サーバーのWordPressから新サーバーのPureBuilder Simplyに変更する
  • Webメニューを完全JavaScriptフリーにする
  • Postfix/Dovecotを引っ越しする
  • DNSサーバーをConoHaとし、DNSの設定を変更する
  • 一部のドメインを廃止とする
  • 一部のドメインの役割を変更する
  • Let’s EncryptによるSSL証明書を取得し、HTTPSに対応する
  • 同証明書にメールも対応させる

なお、あまり詳細な解説はしていない。 Linuxやサーバーに関する基本的な事項に対して理解していないまま実施するのは危険であるため、 「コピペ仕様」にはしていない。 詳細に対してエラーが生じるなどの理由でより情報が欲しい場合はあるだろうが、 「言っていることが理解できない」のであれば、サーバー構築をするにはまだ危険なレベルにあると思ったほうが良いだろう。

承前: 開発

PureBuilder Simplyの開発

今回のために新しいコンテンツシステムであるPureBuilder Simplyを開発した。 この詳細は別に譲ろう。

テンプレートの開発

PureBuilder SimplyはPandocテンプレート+eRubyテンプレートというテンプレートを扱うことができる。 PureBuidler Simplyにテーマファイルがあるわけではないので自分で書く前提である。

今回は複数の表示デザインがあるのだが(現在のところは表示されるのはアーティクルモードとプロモーションモードの2つだけだが)これは全てPandocテンプレートとCSSで実現している。

もちろん、このようなテンプレートの開発はWeb屋の腕の見せ所だろう。

CSS

サイトはそれほど華やかなデザインではないが、技術的に劣っているわけではない。 その最たるものがCSSのみで書かれたハンバーガーメニューとドロワーだろう。

ポイントを簡単に言うと

  • ドロワーはfixedで上部に最初からある。display: noneで、高さは比較的新しい単位であるvhである
  • ハンバーガーメニューはtransitionを使っている
  • z-indexでメニューのほうが上になるようにする
  • 状態変遷は次のような方法でコントロールしている
    • 表示されないチェックボックスを用意し、操作対象をlabelで関連づける。これによりlabelで囲まれた要素をクリックするとチェックボックスがトグルする
    • CSSの+セレクタは同じ親要素を持つ次の兄弟要素に適用される
    • チェックボックスにはチェックが入っているときに適用される疑似要素:checkedがある
    • そこで、チェックボックス本体の直後に対象となるセクションコンテンツを置くことでチェック状態によって状態をトグルできる
    • ドロワーはfixedなのでどこに書いても構わないので、このセクションコンテンツの中におく。場所としてはメニューの位置に基づくのが良いだろう

見た目はWordPress時とあまり変わっていないが、性能は大幅に向上した。

速度

キャッシュの効かない初回アクセスで従来のWordPressページが5.57s、新しいページは約400msと10倍程度高速化した。

ConoHaサーバーのスタートアップ

立ち上げ

ConoHaのサインアップは10分もあれば可能で、即座にサーバーを使いはじめられる。

サーバー仕様は東京リージョンの1GBプランである。

512GBプランは安いが、性能が十分でなく、またマイグレーションができないため、1GBプランとしている。

この時点でサーバー選択が可能なので、Arch Linuxを選択する。 また、この時点である程度のセットアップが可能だ。 ここでSSH公開鍵の登録が可能である。

のようにして専用に生成しておく。 そしてconoharoot.rsa.pubを登録する。 名前からもわかるように、ここで登録する鍵はroot鍵である

また、開放するポートも選択できる。 ここで開放するポートはサーバーよりも上流でフィルタリングされる。 ここで透過していないポートに対するアクセスはサーバーに到達しない。

ただし、結果的にSSHポートの変更はサーバーに負担がかかるものになっている。 少なくともパスワードログインは禁止すべきだろう。

現時点ではSSHのみを通過させる。

初期設定

ConoHaのArch Linuxは標準インストールではなく、ある程度調整されている。 主にSSHログインが可能で、SSH公開鍵が登録され、パスワード認証不可となっている、といったことだ。 こうした内容は/etc/cloud/conoha-init/conoha-init.shによって確認可能だ。

複数のサーバーを接続する予定であれば変更すべき点は多いが、そうでなければ作業は平凡だ。

アップデート

まずはアップデートする。 20MB/sも出るため、超早い。

Zsh

私としてはZshがないと話にならないので入れておく。

これ移行はZshでの作業

一般ユーザーの追加

もちろん、一般ユーザーは登録されていない。

この時点で一旦再起動しないとパスワード設定ができないので、再起動しておく。

パスワードの設定

その上でvisudoを使って%wheelに対するsudoを許可する。

pacaurとyaourtのインストール

AURパッケージも扱う予定であるため、pacaurを入れておく。

# su - jrh
% gpg --recv-keys 487EACC08557AD082088DABA1EB2638FF56C0C53
% sudo pacman -S git

%git clone --depth=1 "https://aur.archlinux.org/cower.git"
%cd cower
%makepkg -si
%cd ..

%cower -d pacaur
%cd pacaur
%makepkg -si

これでAURからのパッケージインストールが可能になったので、Yaourtを入れておく。 作業が明確に自動化されていたり、システマチックに行えるのならYaourtはいらないかもしれないが、 まとめて検索するためには欲しい。

% pacaur -S yaourt

必要なソフトのインストール

ここでいう「必要なソフト」は私の取り扱い上の話だ。

% yaourt -S ruby openbsd-netcat rsync mercurial postfix dovecot nginx fcgiwrap certbot certbot-nginx vim

一般ユーザーでの鍵ログインの準備

サーバーで受け入れの準備をする

% mkdir .ssh

ローカルで鍵を生成しておく。

% ssh-keygen -f ~/.ssh/conoha.rsa

~/.ssh/configに設定する。 これは名前によるアクセスを可能にするためである。 (同一ホストに対する異なる鍵でのアクセスのため、鍵を指定せずに済むようにでもある) もちろん、読み替えること;

Host conoha-root
  User root
  Port 22
  HostName conoha.site.static.cnode.io
  IdentityFile ~/.ssh/conoharoot.rsa

Host conoha
  User jrh
  Port 22
  HostName conoha.site.static.cnode.io
  IdentityFile ~/.ssh/conoha.rsa

rootでは作業できるので、転送する。

% ssh conoha-root 'cat > /home/jrh/.ssh/authorized_keys' < ~/.ssh/conoha.rsa.pub

サーバー側でパーミッションの設定を行う

% sudo chown -R jrh:jrh .ssh
% chmod go-a -R .ssh
% chmod go-a .

そしてsshdリロード

% sudo systemctl reload sshd

DNS設定

ドメインを複数持っていない場合はいきなり完全移行できなかったりするので、 一時的にサブドメインを作るなどする必要がある。

ConoHaコントロールパネルのDNSからDNSの設定を行う。 (DNSの設定ってなんだ、という者はサーバーを立てるにはまだ早い。修行してくるべし)

これは本番サーバーのものを含む。 ただし、稼働中の本番サーバーのアドレスをこの時点で変更してはならない

そして、DNSサーバーをConoHaのものに変更する。

今回の場合従来はドメインサービス提供のDNSを使用していたため、同サービスのメニューから変更を行った。

WebとLet’s Encrypt

Nginxの立ち上げとテスト

従来がDeleGateで、Nginxにするため互換性は全くない。

Nginxは単純にstartすればアクセス可能な状態だが、移行のための準備をしていく。

まずは、Archの記述に合致するようにserver-avilableディレクトリを読むようにしたほうが良いだろう。

http {
    include       mime.types;
    include       /etc/nginx/servers-avilable/*;
    ...
}

これで/etc/nginx/server-avilableを作ればそこに配置したファイルを読むようになった。 この時点でrestartすると…

Dec 19 18:45:42 archlinux nginx[9339]: 2017/12/19 18:45:42 [warn] 9339#9339: could not build optimal types_hash, you should increase either types_hash_max_size: 1024 or types_hash_bucket_size: 64; ignoring types_hash_bucket_size

とのことなので増やす。

http {
    include       mime.types;
    include       /etc/nginx/servers-avilable/*;
    default_type  application/octet-stream;

    server_names_hash_bucket_size       128;
    types_hash_max_size                 4092;
    ...
}

配置するファイルはArchwikiに従ったもので大丈夫だ。

server {
  listen 80;
  listen [::]:80;
  server_name domain.tld;
  root /usr/share/nginx/html;
  location / {
    index index.htm index.html;
  }

  # ACME challenge
  location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    root /var/lib/letsencrypt;
  }
}

domain.tldは適切なドメインに置き換えること。

ここで、あまり書かれていない重要なこと。

rootというのはドキュメントルートで、locationの起点となる。 つまり、

location /foo {
  root /usr/share/nginx/html;
}

であるとき、/foo/bar.htmlにアクセスすると読まれるファイルは/usr/share/nginx/html/foo/bar.htmlであって、/usr/share/nginx/html/bar.htmlではない

そのような単純なマッピングを行いたい場合はrootではなくaliasを使う。

ACME challengeはhttp://domain.tld/.well-known/acme-challenge/randomnumberに対して行われるため、 rootで正しい。

だが、このディレクトリがないので作っておいたほうが良いようだった。

% sudo mkdir -p /var/lib/letsencrypt/.well-known/acme-challenge

あとはcertbotを使えば良いのだが…

% sudo certbot certonly --email webmaster@domain.tld --webroot --webroot-path /var/lib/letsencrypt/ -d domain.tld

その前にConoHaのサーバー設定でHTTPをあけておかなくてはならない。 そして、IPv4とIPv6両方をあけておくこと。 別々になっていることに気づかず、ACME Challengeのリクエストが到達せずに(/var/log/nginx/access.logを見ても記録されていない)随分とハマってしまった。

移行作業

各ドメインごとのドキュメントルートを作り、ファイルを配置、 さらに対応したドメインごとの設定ファイルを作る。

今回の場合、Mimir Yokohamaのページは既にPureBuilder Simplyによる静的ファイルへのビルドが完了しているし、 移行対象のものに関してもPureBuilder2で静的ファイルにビルドされているものなので、単純にファイルを配置するだけの簡単なお仕事である。

Aki SIE関連のアドレスはdiscontinuedなので、301を返す。

server {
        listen 80;
        listen [::]:80;
        server_name aki-sie.com akisie.com aki-sie.yokohama akisie.yokohama;

        return 301 http://www.mimir.yokohama/;
}

http://journal.reasonset.net/に関しては301でリダイレクトしていたので、これも反映する

server {
        listen 80;
        listen [::]:80;
        server_name journal.reasonset.net;
        return 301 http://chienomi.reasonset.net$request_uri;
}

NginxのLet’s encryptの対応

メールサーバーの移行まで完了した時点で作業を行うのだが、 certbotで必要なドメインをすべて署名してもらったら、1SSL対応化を行う。

設定例は以下

server {
  listen 80;
  listen [::]:80;
  listen 443 ssl http2;
  listen [::]:433 ssl http2;

  ssl_certificate /etc/letsencrypt/live/domain.tld/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/domain.tld/privkey.pem;
  ssl_trusted_certificate /etc/letsencrypt/live/domain.tld/chain.pem;
  ssl_session_timeout 1d;
  ssl_session_cache shared:SSL:50m;
  ssl_session_tickets off;
  ssl_prefer_server_ciphers on;
  add_header Strict-Transport-Security max-age=15768000;
  ssl_stapling on;
  ssl_stapling_verify on;

  server_name domain.tld;

  index index.html;
  location / {
    root /var/www/domain.tld/doc;
  }

  # ACME challenge
  location ^~ /.well-known/acme-challenge {
    root /var/lib/letsencrypt;
  }
}

メールサーバーの移行

機能させるために一旦古い証明書で作業しているため、Let’s Encryptの証明書が取れたら証明書ファイルを変更してreload/restartすること。

Postfix

Postfixに関してはCentOS 6とArch Linuxではファイル配置が異なり、 バージョンの違いから設定ファイルの違いも大きく互換性に乏しい。

そこで、CnetOSの設定ファイルを/etc/postfix.centとしてコピーする。 このほか、/etc/alias*も忘れずに移行する必要がある。 また、一旦古い証明書ファイルもコピーした。

設定ファイルの違いを見るため、diffを取る。

% diff /etc/postfix.cent/main.cf /etc/postfix/main.cf > main.diff
% diff /etc/postfix.cent/master.cf /etc/postfix/master.cf > master.diff

このdiffファイルをkwriteで2開く。 今回はNemoのsftp機能を使って開いた。

このdiffを元に手作業で変更箇所を反映していく。 主にssl, auth, virtual関連の変更を反映する必要があった。

virtual関連のファイルは/home/mailuserにあったため、これをコピーする。 ただし、これはvirtualメールボックスを含むため、移行完了までは継続的にアップデートする必要がある。 この前にvirtual用に設定していたmailuserを設定する必要もあった。

% sudo useradd --no-create-home --uid=20000 --shell /bin/nologin --system -U -M mailuser

だが、これだけではグループが適正な値にならない。 そこで、グループIDを変更した上で、ユーザーの所属する主グループIDも変更する。

% sudo vigr
% sudo vipw

Postfixをrestartして完了。

Dovecot

Dovecotに関しては設定ファイルをコピーしてそのまま使うことができた。

Dovecotの設定ファイルとして/home/mailを使っていたので、これをコピーする。

Dovecotをrestartして完了。

上流

DNSを変更してもDNSキャッシュの関係でまだ旧サーバーにもメールが届く。 ある程度はaliasを使って転送しても良いのだが、素直にPostfixで受け取りつつ、Maildirのファイルを同期していくのが良いだろう。

DeleGateを使っていたため、DeleGateのSMTP転送機能を使う方法もあるのだが、うまく動作しなかったのと、TLS接続を受け付けることができないため、諦めた。

セキュリティ関連

複雑な話になるので省略。

そこまで難しいことをしているわけではないが、 普通の対策と、らしい対策とで簡単には突破できないようにしている。

後処理(旧サーバー)

DovecotとDeleGateは停止してしまう。

Postfixは5日程度稼働したら停止してしまっていいだろう。3

その後、バックアップ(主にログや設定など)をとったらサーバー破棄である。

おまけ: ConoHaについて

DNS

ConoHaのDNSは高速である上に非常に設定しやすい。

これまで使用していたお名前.comのもの、XDomainのものは非常に設定しづらかったので、 これだけでもConoHaにする価値はあるレベルだ。

料金

コンピューティングリソースはDTIとあまり変わらないが、料金は約倍になった。

ただし、ConoHaの柔軟性やメリットを考えればそう悪くない。 両方持つと少々負担は大きいが4、一気に完全移行したためDTIを解約でき5、許容すべきコストアップだろう。

速度

速い。

「コンピューティングリソースは大きく変わらない」といったが、速度は明らかにあがった。 特にネットワークの高速化とストレージの高速化の恩恵は大きく、Webの応答性は明確に向上した。

柔軟性

DTI VPSは色々と柔軟性が足りず、困った。 特に、OSのバージョンをあげようにもサーバーがひとつしかないので、できない。 ConoHaなら

  • インスタンスが立てられるのでサーバー仕様変更もできる
  • OSが選べる。さらにカスタムイメージのアップロードも可能
  • サーバーのアップグレードが簡単にできる(512MBプランを除く)

ファイアウォール

上流でフィルタリングしてくれるのはとても嬉しい。 設定が楽になる、というのもあるが、サーバーの耐障害性が勝手にあがる上に、まあまあ重いiptablesでの処理量が減るため、パフォーマンスが改善する。 リソースが限られている中では非常に嬉しい。


  1. Let’s Encryptの証明書はSAN(Subject Alternative Name)に 対応したもので、fullchain.pemが全てのドメインに対応したものになる

  2. Kwrite/Kateにはdiffのハイライト機能があるからだ

  3. TTLは3600だったため、それに従うならば1時間待てば良いのだが…

  4. DTIが月額500円ほど(年間6000円程度), ConoHaが900円ほど(年間10800円程度)である

  5. といっても、私はDTI SIMの契約があるため、DTIの契約そのものが終了するわけではない

PureBuilder2 TopicPath機能の追加

変更点

最新の変更@Gist

概要

これまでTopicPath機能はPureBuilderで提供されて来なかった。
そのため、個別のドキュメントとテンプレートにおいて実装可能な機能として紹介されてきたが、一般的な要望であるため今回の変更で取り込んだ。

このTopicPath機能は整形されたHTMLを返すわけではなく、シンボルと文字列からなる配列を返す。
PureBuilderの本来の設計に従い、サイトの階層構造に等しいディレクトリ構成を採用し、かつドキュメントごとにTopicPathが固定される状態であれば、かなり楽にTopicPathが生成できる。

これまではTopicPathはドキュメントあたりで設定することが勧められていた。これは、ACCS indexが組み込みで機能するためだ。

この機能を使えば設定ファイルによって、そのディレクトリの親パスを定義し、そして文書タイトルがStringとして追加される。

詳細

つまり、ディレクトリで設定されているのが

[ :Foo, :Bar ]journal/

で、文書タイトルがBazであるならば、

[ :Foo, :Bar, "Baz" ]

となる。

別にシンボルである必要はない。だが、シンボルを推奨している。マップを使用することが推奨されているためだ。
だが、特にシンボルであることを期待しているコードは組み込まれていない。

だから、例えば

[ { Address: "http://example.com/foo/", Title: "Foo" }, "Baz ]

のような構造にしても構わない。

実際にそれを使うコードとしては

% tp = DOC.mktopicpath
% tp.each do |i|
%   if i.kind_of?(String)
        <li><%= i %></li>
%   else
        <li><a href="<%= 	DOC.pbenv[:TopicPathMap][i][1] %>"><%= DOC.pbenv[:TopicPathMap][i][0] %></a></li>
%   end
% end if tp

のようになる。

ただし、Indexの場合はディレクトリで定義されている階層は今いるページなのであるから、その場合はtitleとpathの最終エレメントは重複しているはずだ。

そこで、:Indexが定義されている場合は、最終エレメントを取り除くことにした。

過渡期のコード

タイトルは"title"なのか"Title"なのか:Titleなのか、といったところに揺れがある。

正式には"title"を使用することになっている。だが、おそらくはreservedなキーは大文字で始めることにしたほうがいいだろう。

この互換性を維持するコードにしてある。

また、すでにページあたりでTopicPathを設定している場合に備え、現状はdevelブランチのみの対応だ。


途中で放置したため、書くべきことを忘れました。
ゴメンナサイ。

PureBuilder2を使ったリニューアル(1)

PureBuilder1のサイトがPureBuilder2で動作するように調整すると共に、PureBuilder2の機能を検証する作業を開始した。
現在はサイトの更新が滞っているので、それが完了すれば効率的に更新できるようになる。

ただ、従来は設定ファイルにロジックを組み込む形だったため、変更点は大きく、そのまま持ってくるというわけにはいかない。
そもそも、PureBuilder1が十分なツールでなく、ツールをサイトごとに書いて完成というものだったのが問題なのだが。

まず、PureDocドキュメントはそのまま持ち込むことができる。
従来の.rebuild_rulesファイルや、ReasonSetにおけるglobal.rcファイルに変えて、.purenuilderrc.rbを用意することとなる。

おおよそそれでいいのだが、既にrcファイルで組み込んでテンプレートで利用していたような情報は.purebuilderrc.rbファイルに組み込まなくてはいけない。
また、これによって従来環境変数で処理していた物を、DOC.pbenvを使うように整合性をとらなくてはいけない。

このデバッグ作業に伴って、Purebuild Allに.rebuild_all_timeを無視して全てを対象とする-cを追加した。

そして、問題になったのがプロフィール部分だ。

これまで、プロフィールは単独のRubyスクリプトだった。rebuild_rulesから呼ばれることを爽亭しているため、設定は環境変数を通じて受け取ってはいるが、ドキュメントの生成、テンプレートへの埋め込み、そしてファイルの出力までプロフィール自体で行っていた。

しかし、これをそのままにできるわけではない。
設計上、これをPureDocであるとみなした処理したほうが早い。
だが、問題として、設定はあくまでもドキュメントを生成したあとに使えるようになっているため、ドキュメント内で使うことができない。PureDocを拡張してPureBuilder向けスクリプトにすることがかなり難しいのだ。

DOC内の@bodyStringまたはArrayという扱いだったが、実際にStringだと参照時に@body.joinを呼ぶためエラーになってしまう。この点については、PureDocのほうを修正することとなった。

こうした拡張がいまいちしづらいことを考えると、修正が必要かもしれない。
また、既存のPurebuildスクリプトを用いるのではなく、DSLによってビルドを指示できる仕組みも追加すべきだろう。

PureBuilder2(3) Markdown for Blog

今やブログは主に Markdownで書かれている。

当初、blogtrというPuredoc用のスクリプトを書いたが、ブログ程度であれば圧倒的にMarkdownで事足りることが多いからだ。
実のところ、ACCSコンテンツなどでもMarkdownで十分なケースは多く、そのためにPureBuilder2はMarkdownをサポートする。

Markdownを変換し、ヘッダーを操作するblogmdはPureBuilder1.5で既に実装されたが、これはPandocを使ったスクリプトである。
PureBuilder2は全面的にRubyでいく予定であるため、MarkdownトランスレータにはKramdownを使用している。

これに合わせてKramdownを採用することにした。
機能的にはほとんど変わらないが、唯一の違いとして、手前に

* TOC
{:toc}

を入れるようにした。
これにより、KramdownはTOCを自動生成する。Pandocにはなかった便利な機能で、ちゃんとオフセットしたTOCを生成してくれる。

ちなみに、PureBuilderのMarkdown用ライブラリがKramdownをモンキーパッチングで拡張し、自動的にPureDocオブジェクトのメタ情報としてヘッダーを埋め込むので、XHTPureDocを使ってTOCを作ることもできなくはない。

まだpush予定はないため、コードを掲載する。

#!/usr/bin/ruby
# -*- mode: ruby; coding: UTF-8 -*-

require "purebuilder/purebuilder"
require "kramdown"
require "optparse"

opt = {}
op = OptionParser.new

op.on("-m", "--marshal") {|v| opt[:marshal] = true }
op.on("-M", "--without-meta") {|v| opt[:marshal] = false }
op.parse!(ARGV)


# String for Kramdown's TOC
TOC_PREFIX = "* TOC\n{:toc}\n\n"

# Get article file
sourcefile = ARGV.length == 1 ?  ARGV[0] : nil
sourcestr = ARGF.read

pbp = PureBuilder::Parser.new(sourcestr, sourcefile)
pbp.proc_header

html = Kramdown::Document.new(TOC_PREFIX + sourcestr.gsub(//m, "") ).to_html

if opt[:marshal]
  Marshal.dump({body: html, head: DOC.meta}, STDOUT)
else
  puts html
end

これだけ見るとシンプルだが、PureBuilderとの関係が深く、結構中まで突っ込んでみることになってしまった。
PureBuilderの設計があまりよくないのかもしれないとも思ったが、そもそもPureBuilderのMarkdownサポートは「MarkdownをPureDocに見せかける」ものなので、PureBuilderとPureDocの密結合はやむをえまい。

これで初めて動かすこととなったPureBuilderだが、これによってPureBuilder、さらにPureBuilder登場によって修正されたPureDocのバグが発見され、デバッグにかなりの手間を費やした。

基本的にはシンプルだが、オプションへの対応を加えたため、いくらか複雑化した。
オプションは、将来的にパイプしてAPI経由でのブログアップロードに対応するため、メタを含めたMarshalで渡すためのものだ。

PureBuilder2

PureBuilder2とは

PureBuilder2は現行のPureBuilderを置き換える新しいサイトビルドツールだ。 コマンド一発でウェブサイトの更新が可能になる。「動的生成の事前作業化」が可能となる。

PureBuilderからの主な変更点は次の通り

  • Rubyでの実装 (Windowsで動作可能に)
  • MarkdownとeRuby対応

変更点は少ないようにみえるが、PrueBuilderとは互換性はないし、コードも新規に起こす。

Markdownへの対応

Markdownへの対応はKramdownライブラリを使用した。 非常に使いやすく、問題はないように見えた。 何を何に出力するかは、指定クラスの入れ替えによるポリモーフィズムによる。

このラッパークラスはごく簡単だと思ったのだが、そうはいかなかった。

現状、PureDocはライブラリであり、ドキュメントがRubyコードである。 これを出力するためのユーティリティはZshスクリプトになっている。

PureBuilderはその多くをPureDocに依存している。 PureBuilderが直接に依存していなくても、テンプレート側はPureDocオブジェクトを触れることになっているし、現状テンプレートを呼ぶところまでがPureBuilderの仕事なので、当然テンプレートではドキュメントを出力するために、PureDocオブジェクトを必要とする。

だが、当然ながらKramdownオブジェクトはPureDocオブジェクトと互換性がない。 機能を維持するためには、単にKramdownを呼び出すラッパーではなく、Kramdownを内部で使うPureDoc互換クラスが必要となる。

予定とは比べ物にならないほど大変な作業だ。

PureDocのインターフェイス

加えて、今のところPureDoc Translatorが保持している機能については、PureBuilderから使用することができなくなる。 旧来のPureBuilderは、コマンドとしてPureDoc Translatorを呼んでいたため問題がなかったが、ライブラリとして使うとTranslatorは使えない。

PureDocにその機能があるにはかかわらずPureDocに組み込まれていないのは、PureDocの仕様によるものだ。

PureDocの

##-----
...
##-----

という形式でYAMLをヘッダーとして埋め込めるという仕様は、PureDocにはないが、便宜上の拡張としてTraslatorにあり、PureBuilderはそれを前提として使用する。

これをPureDocに組み込むのであれば、PureDocクラスにその機能をいれてしまえば良い。 要はこの仕様をPureDocに取り込むか、PureBuilderに取り込むかの話なのだが、おそらくはPureDocに取り込むのが妥当なところ。

一方同じようにこのヘッダを取り扱いながら、ヘッダにLast UpdateとSinceを書き込む機能があったりするが、これはあきらかにPureDocではなくPureBuilderに実装されるべき機能だ。

一応、いまのところ次の方針を考えている。

  • meta取り込みはPureDoc#read_meta(text)で行う。このヘッダはコメントになっているので、テキストを与える必要がある。これはPureDocライブラリが勝手に実行することはない
  • PureBuilderはpuredoc.metaによりsincelast-updateを確認し、ない場合は追記する

PureBuilder2のおおまかなモデル

purebuilder本体はRubyライブラリとなり、基本的には各ディレクトリの.rebuild_rulesまたは.up*ファイルが処理手順となる。

これらをまとめて呼ぶためのスクリプトが、purebuilder.rebuildallになる。

対象ファイルに対して

PureBuilder.build(file, outputdir, extname)

とすることでビルドできる形だ。

インタープリタ起動役は

rebuildallでrebuildスクリプトのインタープリタは拡張子によって判断するが、拡張子がない場合はperlを使う。

これは、perlはshebang行を解釈するためだ。この機能はsh/bash/zsh/rubyにないことを確認している。 Perlは「Shebangを解釈できないダメなシェルに代わって」起動するそうだが、どうやらLinuxが解釈するだけで、シェルに解釈を期待するのは厳しそうだ。