Compnet

仕事とか遊びとか、日々折々

2016-10-28(金)

実際に記事を書く

Posted by Nakane, R. in technical   

先の記事で Web サイトを生成する作業ディレクトリ作成したので、いよいよ記事を書いていきます。 作業ディレクトリを ~/website にしたので、記事などのコンテンツは ~/website/content ディレクトリに保存します。 記事そのものは reStructuredText の書式に基づいて書き、保存するときの拡張子を .rst にします。

Pelican を動かす環境の Python に Markdown パッケージを追加すれば、Markdown の書式で記事をかくこともできます。 Markdown の書式で書いたときは、拡張子を .md にします。 なお、Markdown の書式には幾多の方言があるようですが、Python に Markdown パッケージこの Web サイトの書式に対応するようです。

なお、reStructuredText 形式の細かい書式については、公式 Web サイトに譲ります。

記事の本文

記事の本文については、特に気にしなくてはならないようなものはありません。 reStructuredText 形式で素直に書けば大丈夫です。 また、Pelican 独自やプラグインによって追加された reStructuredText ディレクティブも使えます。

ところで、reStructuredText といえばドキュメンテーション ビルダーの Sphinx が有名ですが、Sphinx で拡張されたディレクティブは、同等の機能を提供するの Pelican 用プラグインが無ければ使用できません。

メタ データ

Web サイトに掲載する記事などのコンテンツには、記事の本文の他に以下のような情報が付随するのが一般的です

  • 表題 (タイトル)
  • 投稿日、更新日
  • 著者名
  • 要約 (サマリー)
  • 分類 (カテゴリ)、タグ

このような本文に付随する情報を「メタ データ」と呼びます。 ここに挙げた以外にも様々なメタ データがあり、コンテンツを Web ページに変換したり、Web サイトを構築するときに使われます。

メタ データは常にすべてが必要ということはなく、「表題」と「投稿日」があれば、それ以外がなくてもたいていの場合は問題ありません。 省略したメタ データは、Pelican の設定ファイル (pelicanconf.py と publishconf.py) で定義された方法で、適切に値が割り当てられます。 ただし、どのメタ データが必須で、どのように使われるかは、Web サイトのデザイン (テンプレート) の作り方次第で変わります。

メタ データの書き方

Pelican ではメタ データを reStructuredText の「フィールド リスト」として記述します。 具体的には以下のようになります。

:title: コンテンツの表題
:date: 2016-10-18
:modefied: 2016-10-19
:author: N. Ryuji
:category: 分類
:tags: タグ1, タグ2
:summary: コンテンツの要約

これらは必ず本文よりも前に書かなくてはなりません。 たとえ一行でもメタ データ以外の表記があると、その行よりも後ろは通常のフィールド リストとして解釈され、メタ データにはなりません。

メタ データのうちの表題だけは、一番最初の行にセクション タイトルとして書くこともできます。 上の具体例の表題部分をセクション タイトルで書き直すと以下のようになります。 なお、reStructuredText でのセクション タイトルの記述方法は複数ありますが、どの方法でも記述してもかまいません。

コンテンツの表題
================
:date: 2016-10-18
:modefied: 2016-10-19
:author: N. Ryuji
:category: 分類
:tags: タグ1, タグ2
:summary: コンテンツの要約

ファイル名

書き上がった (書いている途中でも) 記事などのコンテンツは content ディレクトリに保存します。 ここでは作業ディレクトリを ~/website にしているので、書いた記事は ~/website/content ディレクトリに保存します。 拡張子は .rst です。 Pelican で HTML 形式に変換するときは、ファイル名はそのままで、拡張子が .rst から .html に置き換わります。 これを踏まえて、ファイル名の拡張子以外の部分は、Web の URI としても適切なものにします。

Web サイト内のリンク先パスの指定

「Web サイト内のリンク先パス」とは、Pelican で構築するひとつの Web サイト内を指し示すリンク先のことです。 Pelican の場合は、原則として記事などのコンテンツを content ディレクトリ (作業ディレクトリが ~/website なら ~/website/content ディレクトリ) に保存します。

Pelican で Web サイトを生成すると、content ディレクトリ (~/website/content ディレクトリ) に保存した記事などのコンテンツのファイルが HTML 形式に変換されて output ディレクトリ (~/website/output ディレクトリ) に保存されます。このとき output ディレクトリ以下の構造は、content ディレクトリ以下のディレクトリ構造をそのままには使いません。 一定の規則に基づいて、独自にディレクトリとファイルを配置します。

このため、ある程度の推測はできるものの、content ディレクトリに保存したファイルの位置から、Pelicann によって変換された後の output ディレクトリ以下のファイルの位置を知るのは少々面倒です。 Pelican ではこの煩わしさを解消するために、content ディレクトリからの相対パスか、リンク元のファイルからの相対パスの先頭に {filename} という文字列を付ける方法が提供されています。

以下のような構成で記事などのコンテンツを書いたとします。

~/
└─ website/
    ├─ content/
    │  ├─ images/
    │  │  └─ photo.jpg
    │  ├─ category/
    │  │  └─ article1.rst
    │  ├─ pages/
    │  │  └─ article2.rst
    │  └─article3.md

この場合において、content/category/article1.rst の中で content/pages/article2.rst へのリンクは、{filename}/pages/article2.rst{filename}../pages/article2.rst のように記述します。 前者が contet ディレクトリからの相対パス、後者がリンク元のファイル (content/category/article1.rst からの相対パス) による記述です。 同様に content/category/article1.rst の中で content/pages/article3.md へのリンクは、{filename}/article3.md{filename}../article3.md のように記述します。

拡張子が .rst のreStructuredText 形式のファイルも、拡張子が .md の Markdown 形式のファイルも、Web サイトで公開するために Pelican で HTML 形式に変換すると拡張子が .html に変わりますが、リンクを記述するときは元の拡張子のままにします。 Pelican の設定によっては、変換のときに拡張子以外のファイル名の部分も変わることがありますが、その場合でも元のファイル名をそのまま記述します。

画像ファイルのように HTML に変換しないファイルの場合も同様です。 content/category/article1.rst の中で content/images/photo.jpg へのリンクは、{filename}/images/photo.jpg{filename}../images/photo.jpg のように記述します。

この他に {filename} に似た {attach} という記述方法が提供されていますが、残念ながら筆者にはまだ理解できません。 なお、{attach} については、Pelican の Web サイトの Mixed content in the same directory の節とその次の Attaching static files の節に書かれています。

Comments