Pico Documentation 日本語訳（ 2014 年 1 月版）

　Pico はフラットファイル CMS です。つまりバックエンドの管理機構もデータベースも必要としません。 単に .md ファイルを "content" フォルダーに作成するだけでページを生成することができます。

Requrements

　Pico を動作させるには PHP 5.2.4 以降が動作している必要があります。 また Apache が動作している環境であれば mod_rewrite も必要とします。

Installation

  1. まず Pico の最新版をダウンロードして解凍します。
  2. （ FTP などで）サーバーにアップロードします。
  3. 以上。必要に応じて .htaccess を変更してください。

　Pico をインストールしたルートディレクトリにある config.php を編集することで 初期設定を変更できます。 config.php は初期設定がリスト化されています。 設定を変更するには単に config.php ファイルの中身をコメントアウトするか 個別の値を設定すればいいだけです。

Creating Contents

　Pico はフラットファイル CMS です。つまりバックエンドの管理機構もデータベースも必要としません。 単に .md ファイルを "content" フォルダーに作成するだけでページを生成することができます。

　content フォルダ内にフォルダを（たとえば content/sub のように）作成し、 そこに index.md ファイルをおくと、http://yoursite.com/sub という URL でアクセスできるようになります。 その sub フォルダに別のページが作りたければ、 単に異なる名前のテキストファイルを（たとえば content/sub/page.md のように）作成すれば、 http://yoursite.com/sub/page という URL にアクセスできるようになります。

以下にコンテンツの設置位置とその URL の例を示します。

Physical LocationURL
content/index.md/
content/sub.md/sub
content/sub/index.md/sub (same as above)
content/sub/page.md/sub/page
content/a/very/long/url.md/a/very/long/url

　ファイルが見つからない場合は content/404.md ファイルで生成されるページが表示されます。

Text File Markup

　テキストファイルは Markdown 記法を 用いてマークアップします。 また標準的な HTML 記述を含めることもできます。 またテキストファイルの先頭に、コメントブロックを置いてページの属性を指定することができます。

例：

/*
Title: Welcome
Description: This description will go in the meta description tag
Author: Joe Bloggs
Robots: noindex,nofollow
Date: 2013/01/01
*/

　これらの値はテーマの中で {{ meta }} 変数として使用できます（後述参照）。 また同様に、特定の変数はユーザーのテキストファイルの中でも使用することができます。

  • %base_url% - Pico サイトの URL

Themeing

　Pico をインストールすると "themes" フォルダーにテーマを作成することができます。 テーマの例として初期設定されているテーマを参考にしてみてください。 Pico は Twig を テンプレートエンジンとして使用しています。 config.php の中で $config['theme'] 変数を設定することでテーマを選択することができます。

　すべてのテーマは HTML 構造で書かれた index.html ファイルを含みます。 テーマの中で使える Twig 変数は以下の通りです。

  • {{ config }} - config.php ファイルで設定された値（たとえば {{ config.theme }} = "default" ）
    • {{ base_dir }} - Pico がインストールされたルートディレクトリのパス
    • {{ base_url }} - Pico サイトの URL
    • {{ theme_dir }} - Pico で使用しているテーマのディレクトリへのパス
    • {{ theme_url }} - Pico で使用しているテーマのディレクトリへの URL
  • {{ site_title }} - （ config.php で定義される）サイトタイトルへのショートカット
  • {{ meta }} - 現在のページのメタ情報
    • {{ meta.title }}
    • {{ meta.description }}
    • {{ meta.author }}
    • {{ meta.date }}
    • {{ meta.date_formatted }}
    • {{ meta.robots }}
  • {{ content }} - （ Markdaown 記法を変換したあとの）現在のページの内容
  • {{ pages }} - サイトコンテンツの集合（コレクション）
    • {{ page.title }}
    • {{ page.url }}
    • {{ page.author }}
    • {{ page.date }}
    • {{ page.date_formatted }}
    • {{ page.content }}
    • {{ page.excerpt }}
  • {{ prev_page }} - （ current_page に関連する）前のページのページオブジェクト
  • {{ current_page }} - current_page のページオブジェクト
  • {{ next_page }} - （ current_page に関連する）次のページのページオブジェクト
  • {{ is_front_page }} - フロントページであるかどうかを示す boolean 値

Blogging

　Pico サイトにブログを追加したい場合は、次のようにします：

  • ポストする .md ファイルをコンテンツフォルダーに置きます。
  • コンテンツフォルダーに投稿するすべての .md ファイルに "Date" 属性をつけて、 それでページと投稿を区別します （つまり "Date" 属性があれば投稿になり、（通常の）ページにはつけません）。
  • テンプレートで以下のように記載してください。：
{% if is_front_page %} <!-- Front page lists all blog posts -->

    <div id="posts">
    {% for page in pages %}
        {% if page.date %} <!-- Note we check for Date field (posts) here -->
        <div class="post">
            <h3><a href="{{ page.url }}">{{ page.title }}</a></h3>
            <p class="meta">{{ page.date_formatted }}</p>
            <p class="excerpt">{{ page.excerpt }}</p>
        </div>
        {% endif %}
    {% endfor %}
    </div>

{% else %} <!-- Single page shows individual blog post -->

    <div class="post">
        {% if meta.title %}<h2>{{ meta.title }}</h2>{% endif %}
        <p class="meta">{{ meta.date_formatted }}</p>
        {{ content }}
    </div>

{% endif %}

Plugins

　プラグイン は "plugins" フォルダーに 新規に PHP ファイルを作成することで追加することができます。 必要であればプラグインは（ plugins フォルダー以下の）サブフォルダでもかまいません。 新規に作成したプラグイン PHP ファイルではそのファイル名と同じクラス名を定義していなければなりません。 my_plugin.php を呼び出すのであれば、My_Plugin と言うクラスを定義する必要があります。

　プラグインは Pico 本体からあらかじめ定義された名前（フック）の関数から呼び出されます。 以下に before_render フックに個別のテンプレート変数を追加する例を示します。

class My_Plugin {

    public function before_render(&$twig_vars, &$twig)
    {
        // Add a custom template variable
        $twig_vars['my_custom_var'] = 'Hello World';
    }

}

以下が利用できるフックとその引数のリストです。

  • plugins_loaded()
  • config_loaded(&$settings)
  • request_url(&$url)
  • before_load_content(&$file)
  • after_load_content(&$file, &$content)
  • before_404_load_content(&$file)
  • after_404_load_content(&$file, &$content)
  • before_read_file_meta(&$headers)
  • file_meta(&$meta)
  • before_parse_content(&$content)
  • after_parse_content(&$content)
  • get_page_data(&$data, $page_meta)
  • get_pages(&$pages, &$current_page, &$prev_page, &$next_page)
  • before_twig_register()
  • before_render(&$twig_vars, &$twig, &$template)
  • after_render(&$output)

注意： 引数は参照 (passed by reference) で渡されますので、値の変更が可能です。

Adding Custom Meta

個別にメタ変数を追加して before_read_file_meta() フックで使う例です

public function before_read_file_meta(&$headers)
{
    $headers['layout'] = 'Layout';
}

これで適切なメタ情報を追加することができます。

/*
Title: Example
Description: This is a description
Layout: 2col
*/

{{ meta.layout }} テンプレート変数からこの値を参照できます。

Contribute

　Pico の作成にあたっては、GitHub リポジトリ をチェックアウトし、 pull リクエストをいただくと助かります。 もしバグを見つけたら the issues page に報告をお願いします。

Attention （このドキュメントに関する注意）

　このドキュメントは Pico のホームページにある Pico Documention を Ellinikonblue.com/Ellinikonblue.net の 中の人が、日本語に意訳したものです。

　落第レベルの英語力しかない人間が訳したもので、 訳者の頭ではこのような日本語で理解しているというレベルのものですので、 その正確性には一切の責任は持ちかねます。 ご了承ください。

  • このエントリーをはてなブックマークに追加