ZineBrewer

ZineBrewer converts Kramdown (=exhanced Markdown) document to HTML for a web media.

Installation

Add this line to your application's Gemfile:

gem 'zine_brewer'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install zine_brewer

Usage

As the converting command:

$ zine_brewer [kramdown_document_filepath]

As the converting server:

$ zine_brewing_server

When you run the command above, or send kramdown_document_filepath to the zine_brewing_server, the convertion is done as below.

  • The header part is converted and written out as "proof/header.txt".
  • The body part is converted and written out as "proof/body.txt".

Enhanced Notation in ZineBrewer

ここでは、Kramdown（拡張Markdown）に加えて記述可能にした、ZineBrewer向けの記法を説明します。Kramdownの記法は、こちら（クイックリファレンス／詳細文法）をご覧ください。

ZineBrewerで扱う原稿は「ヘッダー」と「本文」に分かれます。以下ではそれぞれ説明します。

なお、ZineBrewerは変換したヘッダー、本文をそれぞれheader.txt、body.txtとして、proofフォルダに格納します。

ヘッダー

ヘッダーは6つの項目からなります。各項目は空行を挟んで記述してください。以下の方法で記述を省略することもできます。

  • ---と書く
  • 以下省略。例えば、コーナー名とタイトルだけ書いておき、以下は何も書かない（---も書かない）ということができます。ただし、以下省略でも、最後の■記事ID■：0000だけは書くようにします。

ヘッダーの記述項目:

[

ヘッダー記述例。コーナー名を---で省略、追加CSSは以下省略しています。

---

ヘッダーと本文の境界には、本文ページの起こしを指示する<%-- page -->を記述します。

なお、ヘッダーの最後に記述する■記事ID■：0000は、原則として記述必須です。 例外として、原稿を入れているフォルダの名前を記事ID（「1234」など）にしている場合には省略できます。

上記例をZineBrewerで変換した場合、ヘッダーは次のように出力されます（proof/header.txt）。

本文

本文をHTMLに変換したファイルは、proof/body.txtとして出力されます。

■ページの起こし

本文の各ページの先頭には、ページの起こしとして必ず<%-- page -->を記述してください。 1ページ目の起こしは、ヘッダーとの境界にもなります。

■図の書き方

図は「拡大なし」「拡大あり」「拡大あり（lightbox）」「ハイパーリンク」「プロフィール」の5種類を記述できます。いずれも<<Fig-●>>（●にはアルファベット大文字1字が入る）から書き出します。

また、記述の後には必ず空行を入れてください（空行が指示の終わりを表します）。

(1) 拡大なし――src以外は省略可能。widthとheightはどちらかを指定しておけば、それに合わせて拡大／縮小表示します（他の種類も同様）:

"src: [\u753B\u50CF\u30D5\u30A1\u30A4\u30EB\u540D] \u203B\u4F8B 1234_fig.png\nwidth: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u5E45\u3092\u6307\u5B9A] \u203B\u4F8B 400px\nheight: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u9AD8\u3055\u3092\u6307\u5B9A] \u203B\u4F8B 300px\ncap: [\u30AD\u30E3\u30D7\u30B7\u30E7\u30F3] \u203B\u4F8B 2020\u5E74\u8ABF\u67FB\u306E\u30B0\u30E9\u30D5\n">>

(2) 拡大あり――src以外は省略可能。大きな画像をアップしておき、widthやheightを使って小さく表示させます。なお、キャプションに自動的に［画像クリックで拡大表示］と表示されます。:

"src: [\u753B\u50CF\u30D5\u30A1\u30A4\u30EB\u540D] \u203B\u4F8B 1234_fig.png\nwidth: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u5E45\u3092\u6307\u5B9A] \u203B\u4F8B 400px\nheight: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u9AD8\u3055\u3092\u6307\u5B9A] \u203B\u4F8B 300px\ncap: [\u30AD\u30E3\u30D7\u30B7\u30E7\u30F3] \u203B\u4F8B 2020\u5E74\u8ABF\u67FB\u306E\u30B0\u30E9\u30D5\n">>

(3) 拡大あり（lightbox）――src以外は省略可能。ズーム表示を使いたいときに使用します。やはり、大きな画像をアップしておき、widthやheightを使って小さく表示させます:

"src: [\u753B\u50CF\u30D5\u30A1\u30A4\u30EB\u540D] \u203B\u4F8B 1234_fig.png\nwidth: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u5E45\u3092\u6307\u5B9A] \u203B\u4F8B 400px\nheight: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u9AD8\u3055\u3092\u6307\u5B9A] \u203B\u4F8B 300px\ncap: [\u30AD\u30E3\u30D7\u30B7\u30E7\u30F3] \u203B\u4F8B 2020\u5E74\u8ABF\u67FB\u306E\u30B0\u30E9\u30D5\n">>

(4) ハイパーリンク――srcとhref以外は省略可能。画像をクリックしたときに、hrefで指定したWebページへジャンプさせます:

"src: [\u753B\u50CF\u30D5\u30A1\u30A4\u30EB\u540D] \u203B\u4F8B 1234_book01.png\nhref: [\u30EA\u30F3\u30AF\u5148\u306EURL] \u203B\u4F8B https://www.amazon.co.jp/dp/4798142417\nwidth: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u5E45\u3092\u6307\u5B9A] \u203B\u4F8B 200px\nheight: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u9AD8\u3055\u3092\u6307\u5B9A] \u203B\u4F8B 150px\ncap: [\u30AD\u30E3\u30D7\u30B7\u30E7\u30F3] \u203B\u4F8B \u66F8\u7C4D\u300E\u30B9\u30BF\u30FC\u30C6\u30A3\u30F3\u30B0Go\u8A00\u8A9E\u300F\n">>

(5) プロフィール――人物の写真にプロフィールを付けたいときに使う記述方法です。名前とふりがなは、変換後「名前（ふりがな）氏」という表示になります。また、画像の幅を600pxにすると、プロフィールと幅がそろいます。プロフィールの肩書きやプロフィールの行頭に、半角空白でインデントを入れることが必須です。

"src: [\u753B\u50CF\u30D5\u30A1\u30A4\u30EB\u540D] \u203B\u4F8B 1234_ichigo.jpg\nwidth: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u5E45\u3092\u6307\u5B9A] \u203B\u4F8B 600px\nheight: [\u753B\u50CF\u3092\u8868\u793A\u3059\u308B\u3068\u304D\u306E\u9AD8\u3055\u3092\u6307\u5B9A] \u203B\u4F8B 400px\nname: [\u540D\u524D] \u203B\u4F8B \u5E02\u53E4 \u660E\u5178\nhuri: [\u3075\u308A\u304C\u306A] \u203B\u4F8B \u3044\u3061\u3054 \u3042\u304D\u306E\u308A\ncap: |\n  \u80A9\u66F8\u304D\n  \u30D7\u30ED\u30D5\u30A3\u30FC\u30EB\n">>

テクニック

(1) cap:（キャプション）は、次のように書くと途中改行を入れられます。各行の先頭には半角空白によるインデントを必ず行います。

cap: |
  1

(2) 次のようにimgs:を使うと、複数の画像を並べて表示できます。特に、width:（と画像間のすきま）の合計が670px以内の場合、PC画面では横に並べて表示されます。

"imgs:\n  - src: 1234_book01.png\n    href: https://www.amazon.co.jp/dp/4798154350\n    width: 200px\n  - src: 1234_book02.png\n    href: https://www.amazon.co.jp/dp/4798154369\n    width: 200px\n  - src: 1234_book03.png\n    href: https://www.amazon.co.jp/dp/4798161888\n    width: 200px\ncap: \u300E\u7D1B\u4E89\u4E8B\u4F8B\u306B\u5B66\u3076\u3001IT\u30E6\u30FC\u30B6\u306E\u5FC3\u5F97\u300F3\u90E8\u4F5C\n">>

(3) src:に記述するファイル名の先頭にある「1234_」という記事IDを表す部分は省略できます。代わりに、ヘッダに記述した■記事ID■：で記述した番号が入ります。■記事ID■：がない場合にも、原稿のフォルダ名が記事IDになっていればその番号が入ります。

■コラムの書き方

コラム（囲み）は、===columnと==/columnで挟むことで記述できます。

===columnに対してスタイルを指示できます。例えば、次のように書くと囲み罫線なしで角丸、地色をベージュにした囲みにできます（スタイルの記述方法は後述）。

■divブロックの書き方

ある範囲に対してスタイルを当てたいときなどには、divブロックをつくって、それに対してスタイルを指示します。divブロックは===divと==/divで挟むことでつくれます。

例えば、本文のある範囲の地にグレーを敷きたい場合、次のように書きます。

■画像回り込みの書き方

本文テキストの画像回り込み指定は、画像と回り込ませる本文テキストとを、===wraparoundと==/wraparoundで挟んでやることで行えます。

ただし、画像を右に置くか左に置くかの指定も必要です。画像の記述<<Fig_●>>の上に、画像を右に置く場合には{:.imgR}、左に置く場合には{:.imgL}と記述します。

次の例では、画像を右に置き、その周りに本文テキストを回り込ませます。

また、画像の周りに本文テキストを回り込ませないようにする場合には、本文テキストの各段落の上に{:.ovh}という記述を加えます。

■脚注の書き方

次のように、本文テキスト中の脚注を付けたい言葉などに[^1]などとアンカーを付け、脚注を置きたい場所に[^1]: 〜という形で脚注本体を書きます。脚注本体のコロンを忘れなく。脚注番号には半角英数字が使えます（[^1]、[^imi01]など）。変換後は出現順に[1]、[2]という通し番号による表記に変わります。

なお、ZineBrewerでは、コラムにfootnotesクラスを適用したスタイルで脚注本体を表示するようになっています。通常のコラムの形ではスカスカした見た目になってしまうので、追加CSSでスタイルを当てることをお勧めします。

■定義表の書き方

定義リストの記述を===dtable〜==/dtableで挟むと、左に項目、右に内容のテーブル（表）ができます。キャプション（caption）を定義できるほか、1列目の幅をth-width属性で指定できます。

例えば、次のように記述すると、

{:caption="イベント概要" th-width="20%"}
===dtable

次のように表示されます。

dtable

■スタイルの書き方

最後に、スタイルの記述方法を説明します。

Kramdown（拡張Markdown）では、文字や段落にHTMLの属性を付けることができます。例えば、次のように記述すると、太字部分が赤色になり下線も引かれます。

これは、**必ず出題する**{:style="color:red; text-decoration:underline;"}という部分は、<strong style="color:red; text-decoration:underline;">必ず出題する</strong>と変換されるためです。

ZineBrewerでは、styleのところをもう少し簡潔に書けるようにしてあります。style属性中の指定一つひとつを、パーセント記号とセミコロンで括ります。

また、太字にしないで、ただ赤字・下線引きにしたい場合には、次のように記述します。

段落に対してスタイルを当てる場合には、段落の直前あるいは直後にスタイルを記述します。例えば、次のように記述すると、段落の背景に薄い赤色に敷くことができます（余白も少しとっています）。

{:%background-color:#ffe6e6; %padding:15px;}

行頭の丸数字などを頭出し（ぶら下げ）したいことがあると思いますが、それは次のように記述します。

{:%padding-left:1em; text-indent:-1em;}

Hanging Indent

id属性、class属性、その他の属性

Kramdown（拡張Markdown）の{: }の中には、次のようにしてid属性とclass属性を記述できます。

{:#id_1234 .footnotes}
id

その他の属性はstyle以外、略記方法はありませんが、HTMLと同様に{:rel="lightbox}"とイコールを使った書き方にすれば、何でも指定できます。

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the ZineBrewer project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.