Riji tutorial

001. Rijiのセットアップ

RijiはシンプルなBlogツールです。「日記」の中国語のピンイン発音表記がrìjìであることに由来しています。以下の様な特色があります。

このチュートリアルもRijiを使って作られています。何はともあれまずは使ってみましょう。

インストール

Perl5.10以降の環境があれば以下のコマンド一発でインストールが完了します。

% cpanm Riji

上記の操作を行うと、rijiというコマンドがインストールされます。以降このコマンドを使ってBlogの操作を行います。

セットアップ

適当な空のディレクトリを作り、その中で以下のコマンドを実行すると雛形が作られ、gitのリポジトリ作成、コミットまで自動で行われます。

% riji setup

この状態でディレクトリを見ると以下のようになっていると思います。

% tree
.
|-- README.md
|-- article
|   |-- archives.md
|   |-- entry
|   |   `-- sample.md
|   `-- index.md
|-- riji.yml
`-- share
    `-- tmpl
            |-- base.tx
            |-- default.tx
            |-- entry.tx
            |-- index.tx
            `-- tag.tx

ディレクトリ構成

riji.yml

設定ファイルです

article/

コンテンツ用のmdファイルを配置します。mdファイルを作るとそれに対応したURLでアクセス可能になります。

article直下のmdファイルはデフォルトで share/tmpl/default.tx がテンプレートに使われます。indexのみ例外でindex.txがテンプレートで使われるようになっています。

article/entry/

ブログエントリーのmdファイルを配置するディレクトリです。デフォルトでentry.txがテンプレートに使われます。

share/tmpl/

テンプレートが配置されています。Text::Xslate形式です

share/static/

静的ファイルを配置します。static/... でアクセス可能になります。

起動

何はともあれこの状態で一旦サーバーを起動してみましょう。Rijiには組込のサーバーが付属しており簡単に動作確認可能です。

% riji server
HTTP::Server::PSGI: Accepting connections at http://0:3650/

3650番ポートでサーバーが起動するので、http://songmu.github.io/p5-Riji/blog:3650 にアクセスしてみてください。以下の様に表示されればOKです。

setup

riji setup --force

空じゃない既存のディレクトリにriji setupしたい場合は% riji setup --forceを指定して下さい。GitHub Pagesを使うときなどに便利です。

今回はここまでです。

次回の内容

次回は新たにblogの設定と記事の作成を行います。

002. Blog設定と記事の作成

002. Blog設定と記事の作成

さて、前回はRijiのセットアップを行いました。rijiというコマンドを使ってBlogを操作することを覚えているかと思います。また前回作ったリポジトリが手元にあると思うので引き続き、Rijiを使っていきましょう。

Blogの設定

リポジトリにはriji.ymlが作られていますが、これの中身は以下のようになっています。

author:   'Your name'
title:    "Your Blog Title"
site_url: 'http://yourblog.example.com/'

完全に仮の初期設定なので、自分の環境にあわせて変更してみましょう。site_urlは最終的にアップするサイトのURLに合わせてください。特に決まってないのであれば仮のままで大丈夫です。

変更した状態で% riji serverを起動してBlogを確認してみて下さい。変更内容が反映されているでしょうか？反映されていればriji.ymlをコミットしましょう。これでBlogの設定は完了です。

余談ですが、設定ファイルはTOMLにしようかとも考えたのですが、日和ってYAMLにしました。今後TOMLに対応するかもしれません。

Blog記事の作成

早速記事を作成してみましょう。…と言いたいところですが、まずはsampleのファイルは必要ないので消してしまいましょう。

% git rm article/entry/sample.md
% git commit -m "remove sample.md"

次に、記事を作成しましょう。article/entry/ 以下に配置されていて拡張子が.mdになっていればなんでも良いのですが、今回はstart.mdという名前にして編集してみましょう。

% $EDITOR article/entry/start.md
% cat article/entry/start.md
# blog開設

Rijiを使ってBlogを開設しました。

編集はMarkdown形式でおこないます。DiscountというMarkdownパーサーがデフォルトで使われます。github flavored markdownと比較的互換があると思います。

さて、編集を終えたら、例に因って記事をコミットしてください。それからriji serverをたちあげて、http://songmu.github.io/p5-Riji/blog:3650/entry/start.html にアクセスしてみましょう。以下の様な画面が表示されていればOKです。

edit

Blog記事の追加

さて、もう一つ記事を追加してみましょう。ただ、毎回.mdファイルの名前を考えるのは面倒です。そこで以下のコマンドを使いましょう。

% riji new-entry

今日の日付をもとに、エントリーファイルが作られ、環境変数$EDITORが正しく設定されて入ればエディタも起動します。

ファイル名はローカルの日付を元に'%Y-%m-%d-$postfix'というルールで作られます。'$postfix'の位置には連番が自動で挿入されますが、riji new-entry hogeのようにして、自分の好みのpostfixをつけることも可能です。

それを適宜編集して保存してコミットしましょう。これで2つ目のエントリーが作られました。riji serverを使って確認してみてください。

Blog記事以外のコンテンツの追加

Blog記事ではないコンテンツをサイトに追加したい時もあるでしょう。例えば自身のプロフィールページなどです。

そういったコンテンツは article/ 直下に配置します。プロフィールであれば、article/profile.md と言った具合になるでしょうか。この場合だと、article/profile.htmlにアクセスするとプロフィールページを閲覧できるようになるはずです。

今回はここまでです。

次回の内容

これまではriji serverを使った手元での確認だけでしたが、次回は実際にBlogの書き出しを行います。

003. Blogの書き出しと公開

003. Blogの書き出しと公開

Rijiはriji serverで動的に運用してもいいのですが、静的配信にも対応しています。静的配信できた方が何かと便利ですね。

前回勿体つけて「Blogの書き出し」などといいましたが、Blogの書き出しは実に簡単で以下のコマンドを実行するだけです。

% riji publish

上手く行けばblog/というディレクトリが作られ、その中にサイト一式が格納されているはずです。atom.xmlも入っていますね。

もしかしたら、wgetが無いことを怒られるかもしれません。その場合はwgetをインストールしてください。なんでwgetを使ってるかは実装を見て察してください。

あとは、blog/ディレクトリをどこかにアップロードするだけです。せっかくgitリポジトリになっているので、そのままGitHub Pages等にpushしてしまっても良いんじゃないかと思います。

publishディレクトリの変更

上のようにデフォルトでは blog/ にサイトが作られますが、これを変更したいという要望もあるかと思います。その場合は、riji.ymlにpublish_dirというキーを追加して設定を書いてください。'.' に設定したらカレントディレクトリにドバっと作られます。

GitHub Pagesについて

githubで"[username].github.io"というリポジトリを作成するとそれを自分のサイトとして運用することが可能になります。git pushすればすぐにサイトに反映されるので非常に楽ちんです。Rijiで作成したblogの配信先として検討しても良いと思います。

Githubリポジトリへのページ設置について

[username].github.ioに関してはよく知られるところですが、自分のリポジトリでgh-pagesというブランチを作るとそれもGitHub Pagesとして運用可能であることはご存知でしょうか？これで作られたサイトは http://[username].github.io/[repositoryname]/ というURLでアクセスが可能になります。

具体的には以下の手順で作成します。

親のないブランチを作成
% git checkout --orphan gh-pages
ファイルを全て削除
% git rm -rf *
空じゃないディレクトリにセットアップするので--forceをつけてriji setup
% riji setup --force
追随するブランチがmasterブランチではないので、riji.ymlに追随ブランチの設定をする
% echo 'branch: gh-pages' >> riji.yml
pushする
% git push --set-upstream origin gh-pages

あとはこれまで学んできたようにRijiを運用するだけです。

今回はここまでです。

次回の内容

とりあえず、公開するところまではできましたが、簡素でバランスの悪いデフォルトのデザインの調整等がしたくなってきている頃かと思います。 次回は、静的ファイルの配信について説明します。

004. 静的ファイルの配置と配信

004. 静的ファイルの配置と配信

サイトは公開したものの、デフォルトのイケてないデザインを画像やCSSを使って調整したいと思うでしょう。今回は静的ファイルの配置について説明します。

配置ディレクトリ

静的ファイルは share/static ディレクトリ以下に配置するルールになっています。そこに配置したファイルは /static/image.jpg と言ったURLでアクセス可能となります。share/static/img, share/static/css, share/static/jsなどとディレクトリを掘るのがお行儀が良いかも知れません。

配置した画像は以下のようにすれば、Blogエントリーから参照可能です。

![画像](<: '/static/hoge.png' | uri_for :>)

なんとテンプレートに使われているXslateの記法をmdファイル内でも使えるのが無理矢理なおしゃれポイントです。uri_forを使う必要は必ずしもありませんが、ディレクトリの深さが異なる環境で動かした場合にリンクが切れたりする可能性があるので、なるべく丁寧に指定したほうが良いでしょう。

デフォルトテンプレートで使われているCSS, JSについて

デフォルトのテンプレートでは以下のライブラリが使われています。

色々めんどくさいので同梱はせずに外部リソースに直接向ける形になっています。パーソナルユースだったら十分かなと思います。BootstrapのCDNは公式じゃなかったりして若干不安もありますが、気になるようでしたら自分で適宜テンプレートを調整して下さい。

favicon.ico

ちょっとした例外として、favicon.icoはtmpl/static/favicon.ico に配置すれば'/favicon.ico' | uri_forで参照できるようになっています。

今回はここまでです。

次回の内容

静的ファイルを配置したら、今度はhtmlを編集したくなってくるでしょう。次回はテンプレートの編集について説明します。

005. テンプレートファイルの編集

005. テンプレートファイルの編集

前回、静的ファイルを配置する方法について説明しましたが、今回はいよいよテンプレートファイルの編集を行います。これでひと通りRijiの基本機能をマスターして、自分のBlogサイトを構築できるようになるでしょう。

テンプレートディレクトリ

テンプレートはshare/tmplに配置します。初期状態では以下のようになっています。

% tree share/tmpl
share/tmpl
├── base.tx
├── default.tx
├── entry.tx
├── index.tx
└── tag.tx

テンプレートにはPerlの高速テンプレートエンジンであるXslateを採用しており、拡張子は.txとなっています。Xslateにはいくつかシンタックスがあるのですが、Rijiでは標準のシンタックスである"Kolon"を利用しています。

Kolonのシンタックスについて

詳しくは公式ページから辿れるドキュメント等に説明を譲りますが、KolonはPerl6ライクな文法を提供するテンプレートエンジンになっています。各変数の頭には$がついています。一度代入した変数には再代入不可能であることに注意して下さい。以下のようにすることで変数の中見を描画することができます。

<: $bar :>

Rijiではテンプレート描画時にテンプレートに自動的にいくつかの変数が渡されます。

初期テンプレートの役割について

base.tx

ベースのテンプレートです。Xslateにはテンプレート継承という概念があり、base.txはすべての継承元のテンプレートとして使うことが想定されています。もちろんそれに強制的に従う必要はありません。

すべてのページには変数$blogが渡されますが、このページでもその変数を使うことができます。

default.tx

標準のテンプレートです。article直下のmdファイルに対応するコンテンツを描画するのに利用されます。riji setupでarticle/archives.md というファイルが作られて、archives.html というアドレスでアクセス可能になっているかと思いますが、それはこのテンプレートを使って描画されています。

$blogの他に$articleという変数が渡されます。

entry.tx

ブログエントリー描画用のテンプレートです。中見を見るとわかると思いますが、標準で前後のエントリーへのリンクなどが記述されていることが分かるでしょう。

$blogの他に$entryという変数が渡されます。

index.tx

ブログの全体トップページ用のテンプレートです。

$blogの他に$articleという変数が渡されます。

tag.tx

タグページ用のテンプレートです。タグとは何でしょうか？

実はRijiではBlogエントリにタグを付けることができるのですが、今回はそれには触れません。

$blogの他に$tagという変数が渡されます。

変数について

自動的に渡されるそれぞれの変数には様々なプロパティやメソッドがぶら下がっています。どんなプロパティやメソッドがあるかはここでは細かくは触れませんが、初期テンプレートの中見を見て参考にしてみて下さい。余力があればRiji本体のソースコードを読んでみて下さい。

mdファイル内でのXslate記述について

MarkdownはHTMLを直接記載可能なマークアップ書式であり、かつ、mdファイルの中でXslateの記法も使えることは前回説明したとおりなので、結構複雑なテンプレートをmdファイルの上に書くことも可能です。あまりオススメはしません。

今回はここまでです。

次回の内容

テンプレートの編集まで終わり、ひと通りサイトを編集できるようになったと思います。次回はブログ記事にメタ情報を付加する方法について説明します。今回触れられなかったタグについても取り上げます。

006. ヘッダーセクションを利用したブログ記事へのタグやメタ情報の追加

006. ヘッダーセクションを利用したブログ記事へのタグやメタ情報の追加

ヘッダーセクション

各Blogエントリーのmdファイルの先頭にYAML形式でヘッダーセクションを記述でき、記事に関するメタ情報を記載することができます。

ヘッダーセクションと本文は'---'で区切られます。以下のように記述します。

tags: tag1 tag2
template: entry2
title: title
pubdate: 2013-07-21
paginate: ~
---
# 本文開始
...

ヘッダーセクションは任意記述で、記述する場合もきつような項目のみで、すべての項目を記載する必要はありません。各項目の内容は以下のとおりです。

tags

記事にタグを設定出来ます。カンマ区切りかスペース区切り、もしくは配列で指定可能です。

template

ブログ記事の場合entry.tx、それ以外のarticle/直下のページはdefault.txがデフォルトで使われますが、それ以外のものを使いたい場合に記載します。拡張子は省略して指定します。

title

タイトルを指定します。タイトルを指定しない場合、本文中に最初に現れるヘッダ行がタイトルとして使われます。基本的には使用しなくてよいでしょう。

pubdate

公開時間を指定します。gitから自動的に情報が取得されるためあまり明示的に指定する必要はないでしょう。公開時間まで隠しておくとかそういうことも残念がらできません。

paginate

ページングするかどうかのフラグを設定出来ます。デフォルトfalseです。ページングに関してはまだ仕様が未確定です。

タグについて

タグが指定されたページが作られると、/tag/tagname.html というページにアクセスできるようになり、そのタグが付いた記事を一覧することができるようになります。ブログで使われているタグ一覧は、テンプレート変数である$blog.tags()でアクセス可能になっています。

今回はここまでです。

次回の内容

もうRiji全ての機能は説明したといっても良いでしょう。次回は本チュートリアルの最終回です。

007. 落穂広い

007. 落穂拾い

下書きの管理はどうすればよいか？

Rijiでは追随ブランチ(デフォルトではmaster)にコミットした記事は否応なしに公開されます。では公開したくない下書きの管理はどうすれば良いのでしょうか？

書き上がるまではコミットしないで手元に保存しておく？それはあまりスマートではありません。せっかくgitを使っているのですから、下書き用のブランチ(例えばdraft)を作り、そちらにコミットしておけばよいのです。書き上がったら、そっちのブランチから追随ブランチへcheckoutしてくれば良いでしょう。

コメント機能について

Rijiではコメント機能を用意しておりません。DisqusのようなAjaxベースのコメント機能を利用するのが良いでしょう。

検索窓に関して

Googleのサイト内検索を使えば良いと思います

動的配信について

静的配信はめんどくさいから動的配信したいという人もいるかと思います。その場合は、自分のサーバーにリポジトリをpullして、riji serverを直接動かしても良いでしょう。実はriji serverはplackupと同じ引数を受け取ることができるので、riji server -s Starman -p 9999などと指定することも可能になっています。

注意点としては、コンテンツを追加しても、プロセスの再起動をしないと変更が反映されない部分があるということです。

コミットフック等を利用してサーバーがgraceful restartできるようになっていたりすると美しいですね。その辺り、うまい運用のやり方を編み出して作者に教えてもらえると嬉しいです。

トラックバックに関して

残念ながらトラックバックはオワコンになりました。概念としては個人的に好きだったのですが、多くの人に誤った理解をされ誤った使い方をされた挙句廃れてしまったのは非常に残念に思っています。Rijiにはトラックバック機能はありません。

その他機能追加要望に関して

使っているうちにXslateに関数を追加したい、プラグイン機構を入れたい、等色々要望は出てくるかと思います。

開発は以下で行なっているので随時pull requestやissueを投げていただけると非常に嬉しいです。

https://github.com/Songmu/p5-Riji

終わりに

もし、ここまで読んでいただけた方がいると大変嬉しいです。ぜひRijiを使ってみてください。フィードバックをいただけると作者は泣いて喜びます。