nanoc チュートリアル翻訳

以下の文書は http://nanoc.stoneship.org/help/tutorial/ を翻訳したものです（読みやすさを優先して、ぎこちない日本語になる場合は意訳しています）。 2008/04/05 時点の内容なので古くなっていますので、注意してください。原文は、Denis Defreyne さんによるものであり、クリエイティブコモンズ表示-継承 2.0 で公開されています。この翻訳文書も同様のライセンス、「クリエイティブコモンズ表示-継承 2.0」の下で公開しています。

nanoc のチュートリアル

nanoc のインストール

nanac は Ruby（1.8.5またはそれ以降）と RubyGems を必要とします。すでに RubyGems をインストールしてあるかもしれませんが、そうでないならばここから手に入れてください。

RubyGems をインストールしたら、nanac のインストールは簡単です。端末で次のようにしてください。

sudo gem install nanoc

このチュートリアルに必要なこと

このチュートリアルには、RedCloth が必要です。 RedCloth は、Textileと Markdownの Ruby による実装です。これら2つによって、扱いやすいプレインテキストフォーマットの中に HTML を書くことができます。このチュートリアルでは、Markdown を使います（以前に Markdown を使ったことがなくても心配しないでください - 簡単ですから）。 RedCloth をインストールするには、端末で次のように打ってください。

sudo gem install RedCloth

また、このチュートリアルでは、RedCloth の代わりに（Markdown だけを扱うことができる) BlueCloth を使うこともできます。しかし、不運にも BlueCLoth と Ruby 1.9 の組み合わせはうまく動かないようです。

初めての nanoc によるサイトの製作

nanoc はコマンドラインアプリケーションです。つまり、nanoc を使うためには、一日中、端末にコンピュータマニアのようにコマンドをタイプしなければなりません。まあ、それがクールなアプリケーションすべてが動く方法なんだ（そうではないかも）。こういう理由で nanoc にはスクリーンショットは一つもないのです。

nanoc によるサイトは、特定の構造を持つディレクトリです。自分でそのようなディレクトリを作ることもできますが、 nanoc にそれを任せるのが良いでしょう。このチュートリアルでは、’‘nanoc_test’’ というサイトを作ります。このサイトを作るために、端末で次のようにタイプします。

nanoc create_site nanoc_test

これを正しく行ったなら、スクリーンは次のようになるでしょう。

create  output
create  config.yaml
create  Rakefile
create  tasks
create  tasks/default.rake
create  content
create  content/content.txt
create  content/content.yaml
create  meta.yaml
create  templates/default
create  templates/default/default.txt
create  templates/default/default.yaml
create  layouts
create  layouts/default.erb
create  lib
create  lib/default.rb

今、’‘nanoc_test’’ という名前の nanoc によるサイトが作られました。そのディレクトリに入って、そこでファイルのリストを作ると次のようになるでしょう。

-rw-r--r--  1 ddfreyne  ddfreyne  123 14 Dec 09:19 Rakefile
-rw-r--r--  1 ddfreyne  ddfreyne   48 14 Dec 09:19 config.yaml
drwxr-xr-x  9 ddfreyne  ddfreyne  306 14 Dec 10:49 content
drwxr-xr-x  3 ddfreyne  ddfreyne  102 14 Dec 09:19 layouts
drwxr-xr-x  3 ddfreyne  ddfreyne  102 14 Dec 09:19 lib
-rw-r--r--  1 ddfreyne  ddfreyne  322 14 Dec 10:37 meta.yaml
drwxr-xr-x  9 ddfreyne  ddfreyne  306 14 Dec 10:50 output
drwxr-xr-x  3 ddfreyne  ddfreyne  102 14 Dec 09:19 tasks
drwxr-xr-x  3 ddfreyne  ddfreyne  102 14 Dec 09:19 templates

これらすべてのディレクトリがどういうものなのか、少しの間、着実に説明します。

サイトのコンパイル

何をするよりも前に、現在のワーキングディレクトリがあなたが今、作ったサイトであることを確かめましょう。 ‘‘create_site’’ を除いたすべての nanoc コマンドは nanac サイトである現在のワーキングディレクトリで実行しなければなりません。

新しい nanoc サイトは完全に空ではありません。 1つの最小のホームページとこのホームページで用いている最小のレイアウトを備えています。

そのサイトを見る前には、コンパイルする必要があります。

すべてのページはサイトディレクトリ（後ですぐに見るように、正確には、content ディレクトリの中に）にコンパイルされていないソースの形で保存されています。このサイトをコンパイルするにはこのようにしてください。

nanoc compile

nanoc がコンパイルしているとき、端末には次のように表示されます。

Compiling site...
      create  output/index.html
Site compiled in 0.02s.

index.html というファイルが output ディレクトリに作られます。ウェブブラウザでそのファイルを開く（私は safari を使います）と、 “I’m a brand new root page. Please edit me!”. と書かれたとてもシンプルなウェブページが表示されます。それが HTML ページであることを疑うならば、エディタでファイルを開き（私は TextMate を使います）、ページのソースを確認してください。

ホームページの編集

nanoc が実際、どのように動くかを知る最初のステップはホームページのコンテンツを編集してみることです。最初に、とはいってもコンパイルされていないページがどのように保存されているかの簡単な説明を行います。

nanoc サイトのページは content ディレクトリに保存されています。現在、そのディレクトリはたった2つのファイル（content.txt、content.yaml）しかありません。これら2つのファイルは、合わさってホームページを作ります。 .yaml で終わるファイルはページの属性（メタデータ、プロパティ、またはそのような類のもの）を特定します。もう一方のファイルは、実際のページコンテンツを含みます。このことは混乱するかもしれませんが、一度、サイトにページを追加するとなるほどと思うはずです。少しの辛抱です。

ホームページコンテンツをあまり一般的でない何かに変えましょう。 content.txt を開き、そのテキストを何かに変えます。例えば、次のようにします。

<p>Welcome to my new nanoc site! Denis is my hero!</p>

変更を確かめるためには、まずサイトを再コンパイルする必要があります。そこで、次のようにします。

nanoc compile

そして、次のように表示されます。

Compiling site...
      update  output/index.html
Site compiled in 0.02s.

output ディレクトリにある index.html をウェブブラウザとテキストエディタで再び開き、ページが本当に更新されているかを確かめます。

変わっていないものはページタイトル、つまりブラウザのタイトルバーに表示されるタイトルです。ページタイトルはページのメタファイルで定義されます。そのようなメタファイルは、ページに関するすべてのメタデータ、すなわち、このページで使われるレイアウト、ページタイトル、そのページの著者、このページが作られた時間など、を含みます。ホームページメタファイル、content.yaml は次のようになります。

# Built-in

# Custom
title: "A New Root Page"

このファイルは2つのセクション（Built-in、Custom）にわかれています。 Built-in セクションでは、nanoc 自体によって使われるメタデータを書き込むことができます。例えば、layout 属性はこのページが使うレイアウトを決めるために用いられます。 built-in 属性の完全なリストがマニュアルの chapter2 にあります。

Custom セクションは nanoc によって使われないカスタムメタデータのためです。すべての属性は built-in でなければ custom です。カスタムメタデータは、ページタイトル、このページに関連するキーワード、ページの著者の名前、そのページで使われている言語などを含むことができます。

現在、ホームページのメタデータは title 属性一つです。これを、次のようなクールなものに変えましょう。

title: "The Guild of nanoc: a fan website dedicated to nanoc"

サイトを再コンパイルして、ブラウザで index.html を開きます。今、ブラウザのタイトルバーはページタイトルを表示しています。ここに関連する魔法は何もありません。すぐにすべてがはっきり分かるでしょう（もしくは、待つことができないなら layouts/default.erb でのピークを取ることができます。）

ページの追加

サイトに新しいページを追加するためには、 create_page コマンドを使います。次のようにして about ページを作りましょう。

nanoc create_page about

次の表示を見ることになるでしょう。

create  content/about
create  content/about/about.yaml
create  content/about/about.txt

今、2つのファイル（コンテンツファイルとメタファイル）が入っている content/about ディレクトリがあります。そのコンテンツファイル（content/about/about.txt）を開き、次のようにその中にいくらかテキストを書きます。

<p>This is the about page for my new nanoc site.</p>

次のようにメタファイル（YAML ファイル）を編集します。

#Built-in

#Custom
title: "The Guild of nanoc -- About the Guild"

サイトを再コンパイルして、 output/about/index.html が作られたことを確認します。そのファイルをウェブブラウザで開き、あなたのブランドの新しい about ページに見入ってください。

レイアウトのカスタマイズ

おそらくすでに気づいているように、ページのコンテンツファイルは本当の HTML ファイルではなくて、それらは HTML ファイルの一部です。正しい HTML であるためにはページは <html>、<head>、<body>、……のタグを必要とします。このことは終始、誤った HTML を書いているということを意味しません。なぜなら nanoc はコンパイル過程の一部としてそれぞれのページのレイアウトを作成するからです。

layouts ディレクトリを見てください。そこには default.erb というファイルが1つあります。これはホームページと about ページで使われるレイアウトです。テキストエディタで default.erb を開いてください。このファイルは次のようになっています。

<html>
  <head>
    <title><%= @page.title %></title>
  </head>
  <body>
<%= @page.content %>
  </body>
</html>

このファイルは、実際には HTML ではありません。埋め込み Ruby ソースを持つ HTML です。サイトをコンパイルするときに、 nanoc はコンパイルされる必要があるページを調べて、 @page 変数の中にそれを入れます。そのとき、nanoc はレイアウトを評価します。 <%= @page.title %> はページタイトルに、 <%= @page.content %> はページコンテンツにそれぞれ置き換えられます。よって、コンパイルされたホームページは次のようになるでしょう。

<html>
  <head>
    <titleThe Guild of nanoc: a fan website dedicated to nanoc</title>
  </head>
  <body>
<p>Welcome to my new nanoc site! Denis is my hero!</p>
  </body>
</html>

埋め込み Ruby （eRuby としても知られる）に慣れていないなら、 eRuby info site、 eRuby article on Wikipedia、 Prgramming Ruby の “Ruby and the Web” の章 “Embedding Ruby in HTML” section を見てください。

このレイアウトをさらに高度にしましょう。すべてのドキュメントにカスタムメタデータを加えることができるということを覚えていますか。デフォルトレイアウトに author メタデータ属性を表示させましょう。現在、どのドキュメントにも author をセットしていませんので、レイアウトの中でこのことに注意しましょう。更新したレイアウトは次のようになります。

<html>
  <head>
    <title><%= @page.title %></title>
  </head>
  <body>
<% unless @page.author.nil? %>
  <p>This page was written by <%= @page.author %>.</p>
<% end %>
<%= @page.content %>
  </body>
</html>

about ページにページの著者をセットしましょう。 content/about/about.yaml を開いて、以下の行をカスタムセクションに追加します。

author: "John Doe"

サイトを再コンパイルして、output/index.html を開き、 output/about/index.html ページをブラウザで開きましょう。予想通りに、”This page was written by John Doe” と書いてあるページが見えるはずです。

Markdown によるページの記述

HTML でページを書かなければなりませんが、 HTML に変換することができる他の言語を変わりに使うとより簡単になります。この例では、HTML を書くことを避けて Markdown を使います。 nanoc はこれらのテキスト変換フィルタを呼ぶことができます。

ホームページのコンテンツを取り除いて、ある Markdown 形式のテキストに変えましょう。 content/content.txt を開き、代わりに次のように書き込みます。

A First Level Header
====================

A Second Level Header
---------------------

Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.

The quick brown fox jumped over the lazy
dog's back.

####Header 3

> This is a blockquote.
> 
> This is the second paragraph in the blockquote.
>
> ## This is an H2 in a blockquote

サイトを今コンパイルしたなら、コンパイルされた HTML ページは Markdown 形式から変換された HTML を表示はしません。なぜなら nanoc にこのページを Markdown としてフィルターにかけるように伝えていないからです。ホームページのメタファイルを開き、 build-in セクションに次の行を追加してください。

filters_pre:
  - "redcloth"

filters_pre はページを配置する前に動かすべきフィルターのリストをもつ属性です。また、filters_post を使うことでページを配置した後にフィルターを実行することもできます。マニュアルの Chapter 2 には使うことができる built-in フィルターのリストがあります。

今、nanoc にこのページが RedCloth を使うことを知らせました。（このときにエラーが出た場合は、このチュートリアルの初めに記述したように RedCloth がインストールされているかを確認してください）。 output/index.html のページソースはこのようになるでしょう。

<html>
  <head>
    <titleThe Guild of nanoc: a fan website dedicated to nanoc</title>
  </head>
  <body>
<h1>A First Level Header</h1>

<h2>A Second Level Header</h2>

<p>Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.</p>

<p>The quick brown fox jumped over the lazy
dog's back.</p>

<h3>Header 3</h3>

<blockquote>
    <p>This is a blockquote.</p>

    <p>This is the second paragraph in the blockquote.</p>

    <h2>This is an H2 in a blockquote</h2>
</blockquote>
  </body>
</html>

カスタムコードの記述

nanoc サイトには lib という名前のディレクトリがあります。そこでは、Ruby ソースファイルを加えることができ、それらはサイトをコンパイルする前に読み込まれ実行されます。よって、これは助けとなるメソッドを定義するうってつけの場所です。

例として、いくつかのページにあるタグを追加し、数行のカスタムコードを使ってクリーンな方法でそれらのページに表示させましょう。 about ページにいくつかタグを追加することから始めます。 about.yaml を開いて、custom セクションの終わりにこれを追加します。

tags:
  - "foo"
  - "bar"
  - "baz"

次に、lib ディレクトリの中に tags.rb というファイルを作ります。その中で、以下の関数を定義します。

def tags
  if @page.tags.nil?
    '(none)'
  else
    @page.tags.join(', ')
  end
end

この関数は現在のページのタグを取得し、タグのコンマで区切られたリストを返します。タグが何もなければ、”(none)” を返します。この種のコードを使うためには、 default レイアウト開き、<%= @page.content %> の行の上に次の行を追加します。

<p>Tags: <%= tags %></p>

サイトを再コンパイルして、output ディレクトリにある HTML ファイル2つを見てください。すべてがうまくいったなら、ページコンテンツの上に正しいタグのリストが表示されるでしょう。

この例は少し効果が薄いかもしれません。結局、次のようにタグを生成するコードをレイアウトに直接埋め込むことができます。

<p>Tags: <%= @page.tags.nil? ? '(none)' : @page.tags.join(', ') %></p>

しかし、埋め込み Ruby を HTML に入れることは、すばやくできますが汚くなるかもしれません。この例はまだ受け入れられますが、もっと大きなコードを必要とするケースでは、分割された関数を作り、必要なところでこの関数を呼ぶことがベストです。

パスの扱いに関する注意

パスに関して、知っているべき扱いにくい事柄が1つあります。間違いやすいことを示すために、 style.css という名前のスタイルシートを output ディレクトリに作りましょう。そこには、次のように書き込みます。

h1, h2, h3 { color: red; }

ウェブサイトのスタイルシートにリンクを張るためには、レイアウト（default.erb）を開き、次の1行を追加してください。

<link href="style.css" rel="stylesheet" type="text/css">

今、サイトをコンパイルし、index.html を開くと、すべてのヘッダーが赤くなっています。しかし、about/index.html のヘッダーは赤くなっていません。ウェブブラウザは存在しない about/style.css を探します。

もっとも明解な方法は、次のように（スラッシュを加えて）絶対パスを使うことです。

<link href="/style.css" rel="stylesheet" type="text/css">

output ディレクトリの中のコンパイルされたファイルは、ダブルクリックで開いたなら、間違いなくスタイルが適用されていないが、これで良いのです。サイトがウェブサーバにアップされたときに、ウェブブラウザはスタイルシートを見つけるでしょう。

これはローカルでもはやサイトをプレビューすることができないことを意味しますが、これに対してきちんとした解決法もあります。 nanoc はオートコンパイルを備えていて、それはオンザフライでページをコンパイルするウェブサーバです。より重要なことであるが、 output ディレクトリはそのウェブのルートであり、よって、絶対パスは何の問題もない。それをスタートするには、次のようにします。

nanoc aco

これによって localhost のポート 3000 でサーバをスタートします（必要なら -p によってポートをカスタマイズすることができます）。今、http://localhost:3000/ を開くと絶対パスによってうまくいくようになります。

おわりに

これでチュートリアルは終わりです。このチュートリアルがあなたの意欲を刺激し、 nanoc を使い始めるための十分な情報を与えることを願います。

さらに読むものがあります。間違いなくマニュアルは確認する価値があります。大きめですが、nanoc について知る必要があることはすべて含んでいます。

Tags of current page

ruby, nanoc, web