Metalsmith

主要プラグインの一覧と解説

2016.6.29

Table of contents

metalsmith-drafts

ドラフト（下書き）を管理するプラグインです。下書き状態としたいコンテンツファイルの先頭 (YAML front-matter) に draft: true と記述すると、パイプラインから除去されます。

ただし、この方法だと下書き状態のまま生成物を確認することができません。 実例として development 環境では下書きも生成するが production 環境では除去したい、 を実現するには以下のようにします。

$ export NODE_ENV=development

function draftsInDev() {
  if (process.env.NODE_ENV !== 'development') {
    return drafts();
  } else {
    return function(){};
  }
}

  .use(draftsInDev())

export の管理には npm パッケージの dotenv を使うと便利です。

metalsmith-autoprefixer

Autoprefixer プラグインです。 CSS ファイルを対象に、ベンダープレフィックスを自動で付加します。 Sass や Less プラグインを使っている場合には、その後に呼び出します。

metalsmith-sass

Sass プラグインです。拡張子.sassまたは.scssファイルを CSS に変換します。 ただし、Sass のソースファイルや配置ディレクトリをプラグインに渡す必要はありません。 Metalsmith の流儀として、すべてのソースファイルがプラグインの処理対象となるからです。

!! Incompatible with Node v6.x

2016/06 現在、"node-sass": "^3.1.2" に依存しているため Node v6.x では動作しません。 Fork してなんとかするか、 Sass を諦めて metalsmith-less に切り替えます。

パーシャルについて

ファイル名が_variables.sassなどのように先頭にアンダースコアが付いている場合、 パーシャルと判断され出力ファイル群から削除されます。もちろん削除されると言っても、 プラグイン間に流れる処理過程のソースファイルから除去されるだけであり、元のファイルは残ります。 そのため、パイプライン内のパーシャルファイルが消えても、変換対象の Sass ファイルは ソースディレクトリにそのまま残っているパーシャルを import などで参照することができます。

参考までに、パイプライン内のソースファイル名を列挙するコードを紹介します。 下記のコードで本プラグインの記述を挟むと、パーシャルが消え Sass ファイルの拡張子が.cssに変わる様子が見られます。

  .use(function(f,m,d){console.log(Object.keys(f));d();})

outputDir オプション

変換した CSS ファイルの出力先は Metalsmith.destination() + outputDirOption で定義されます。 outputDir オプションに css/ のようにパス文字列を渡すとそこにすべて配置されます。 この場合、元あった階層は維持されません。構造を維持したい場合はオプションにパス文字列を変換する 関数を渡します（詳しくはプラグインの README 参照）。 公式サンプルのように replace を使って、scss フォルダにあったファイルを css フォルダに配置することができます。

metalsmith-less

Less プラグインです。拡張子 .less ファイルを CSS に変換します。 上記 Sass プラグインと同様、ソースファイルや配置ディレクトリをプラグインに渡す必要はありません。 Metalsmith の流儀として、すべてのソースファイルがプラグインの処理対象となるからです。

対象とする Less ファイルはオプションの pattern で指定することができます。

metalsmith-assets

Metalsmith.source() で定義したソースファイル群に、そことは別のディレクトリにあるアセットファイル（各種ライブラリや画像）を含めます。 例えば Metalsmith で扱うコンテンツがマークダウンで、ソースフォルダには .md ファイルのみを配置したい、 アセットファイルはあえて別の階層に置いて管理したい、という場合に役立ちます。

実際にはサイト固有のスタイルシートを用意することと思います。今どきは Sass などを使うのが便利なため、 metalsmith-sass プラグインと組み合わせてビルドすることになるでしょう。

metalsmith-markdown-remarkable

Markdown の実装の1つである Remarkable を使って、拡張子.mdまたは.markdownファイルを HTML に変換します。プラグインに渡された引数は内部 Remarkable の function にそのまま渡しているため、透過的に扱うことができます。引数の preset や options だけでなく、Remarkable 自体のプラグイン機構であるuse()を適用することもできます。

Remarkable plugins

metalsmith-asciidoc

AsciiDoc の実装の1つである Asciidoctor.js を使って、拡張子 .adoc または .asciidoc ファイルを HTML に変換します。

metalsmith-prism

Prism.js を使ってシンタックスハイライトを実現します。 拡張子がhtmlまたはhtmのファイルを対象に適用されます。 Markdown プラグインを使っている場合は、それよりも後にこのプラグインを動作させる必要があります。

metalsmith-jade

Jade プラグインです。拡張子 .jade を HTML ファイルに変換します。

useMetadata オプション

Metalsmith のメタデータを Jade 内の処理で扱えるように渡すかどうかを指定します。

metalsmith-layouts

A metalsmith plugin for layouts

metalsmith-permalinks

例えば about.html であれば about/index.html に変換して出力することで、 以下のような URL でアクセスできるようにします。URLのindex.htmlは省略できることを利用しています。

ファイル管理上の利点

このプラグインの強みはファイル毎に定義したメタデータで出力先を振り分けることができることです。 言い換えるとURLで表現するディレクトリの通りに配置しなくてもよいのです。 例えば、カテゴリを含まない記事IDでアクセスするようなURL構造のサイトを考えます。 コンテンツが充実してくると、1つのフォルダに100を超えるような Markdown ファイルで溢れ返ります。 これらを内部的に日付やカテゴリで区切って整理するものの、URLはその構造を隠して短く、といったことが実現できます。

使用上の注意

対象となるHTMLファイルと同じ階層にあるのファイル（拡張子.html以外）を複製して 新しいディレクトリを作り出すことで実現しているため、無駄なファイルがどんどん増えてしまいます。 これは変換前のHTMLに記述された画像などの参照情報が同階層に対して行われている可能性に対する配慮と思われます。

この挙動はオプション relative を使って OFF にすることができます。 OFF にすると同階層に対する参照が失われるため、同階層の画像などを別の場所に移し、 ルートパスを使った書き方にすることで対処します。 デメリットとしては、例えば Markdown 記述時の画像の配置先が離れること、参照先もそれを意識した 記述とする必要があることが挙げられます。ローカルのエディタ上で画像もプレビューしながら書くためには、 ルートパスの記述に対応したエディタを選ぶ必要があります。参考までに、Atom は対応しているようです。

metalsmith-mapsite

sitemap.js を使ってサイトマップ (sitemap.xml) を生成するプラグインです。

hostname オプション（必須）

URL を生成するための、ベースとなるパスを指定します。 例えばこのサイトのように GitHub Pages のプロジェクトページとして公開する場合は 'https://syon.github.io/refills/' となります。 他のオプションを使用しない場合に、引数をオブジェクト形式ではなく文字列として1つ渡すと hostname 扱いしてくれます。

omitIndex オプション

URL の末尾が index.html の場合に除外します。 metalsmith-permalinks を使うときに便利です。

metalsmith-watch

A metalsmith plugin to watch for a changes and trigger rebuilds.