電書ちゃんのでんでんコンバーター

Just another 'Markdown to EPUB 3' converter.

でんでんコンバーターが利用する設定ファイルの使い方について解説します。

でんでんコンバーターでコンテンツを変換する時、素材ファイルとともに ddconv.yml という設定ファイルをアップロードすると、変換の度に本の情報を入力する手間を省くことができるばかりか、詳細な書誌情報を入力することができるようになります。

設定ファイルの例を以下に示します。

# ddconv.yml
# YAMLで記述されたDDconvの設定ファイルです。
# 「#」以降のテキストは無視されます。
# -------------------------------------

# バージョン
ddconvVersion: 1.0 # 必須。この行は編集しないでください。

# 出版物の識別子
#identifiers:
#  - content: d0df4f65-822d-4714-bd24-c53306fe065c # 具体的な識別子を指定します。
#    identifier-type: uuid # 「uuid」または「isbn」を指定します。

# タイトル
titles:
  - content: 蜘蛛の糸 # タイトルを指定します。(必須)

# 作成者等
creators:
  # 作成者1 --------
  - content: 芥川 龍之介 # 著者などの名前を指定します。

# 出版物が使用する言語(必須)
language: ja #日本語=ja、英語=enなど

# 出版年月日
#date: 20130214 # YYYYMMDDの形式で指定します。

# ページ送り方向
pageDirection: rtl # 横書き=ltr、縦書き=rtl

# EPUB出力オプション
# true: 有効、false: 無効
options:
  skipCover: true  # 表紙ページをスキップする true|false
  titlepage: false # 扉ページを自動生成する true|false
  tocInSpine: true # 目次ページを自動生成する true|false
  tocDisplayDepth: 6 # 目次ページに表示する目次の階層を指定する 1-6
  displayLandmarksNav: true # 目次ページにランドマークを表示する true|false
  displayLoiNav: true # 目次ページに図版一覧を表示する
  displayLotNav: true # 目次ページに表一覧を表示する true|false
  kepub: false # kobo Touch向け拡張子「.kepub.epub」を利用する true|false
  autoTcy: true # 自動縦中横を有効にする true|false
  tcyDigit: 3 # 自動縦中横にする半角数字の桁数を指定する 2-n

基本的な使い方

設定ファイルを使った利用手順は次のとおりです。

  1. こちらから、設定ファイルのテンプレートをダウンロードして、中の ddconv.yml を作品のディレクトリにコピーします。

  2. ddconv.yml をメモ帳等のテキストエディタで開き、作品の内容にあわせて編集してください。エンコーディングはUTF-8にします。

  3. アップロード欄で、テキストファイル等の素材ファイルとともに ddconv.yml も選択してアップロードしてください。

  4. タイトルの入力欄に適当な文字(「あ」でも「a」でも構いません)を入力して、変換ボタンを押します(この時タイトルに入力した文字は、タイトルには使われません)

警告

設定ファイルではインデント(字下げ)の数が重要な意味を持ちます。インデントを変更すると正しく解釈されませんので注意してください。

設定ファイルをアップロードした場合、トップページで入力した「タイトル」や「作成者」、「オプション」等の項目は、内容に関わらず全て無視されます。ただし、タイトルの入力欄だけは必須入力チェックが行われているため、適当な文字を入れてチェックを回避してください。

設定ファイルの内容

バージョン情報 ddconvVersion

  • 必須

設定ファイルのバージョン情報を記述します。現在のバージョンは 1.0 です。この情報は必ず入れるようにしてください。

ddconvVersion: 1.0

識別子 identifiers

  • 任意

EPUBファイルには、その出版物だけが持つ固有の識別子が必要です。でんでんコンバーターでは、変換の度に UUID という識別子を自動生成して付与していますが、本来ならば、同じ作品は、大きな改変が行われない限り同じ識別子を使い続けるのが望ましいです。

設定ファイルで識別子を指定すると、でんでんコンバーターはその値を識別子として使用します。指定できる値は UUID または ISBN です。

次の例では特定のUUIDを識別子に指定しています。

identifiers:
  - content: d0df4f65-822d-4714-bd24-c53306fe065c
    identifier-type: uuid

次の例では特定のISBNを識別子に指定しています。

identifiers:
  - content: 978-4-00-310101-8
    identifier-type: isbn

次の例ではUUDIとISBNの両方を識別子に指定しています。通常は一番上に書いた識別子が利用されます。

identifiers:
  - content: d0df4f65-822d-4714-bd24-c53306fe065c
    identifier-type: uuid
  - content: 978-4-00-310101-8
    identifier-type: isbn

identifier-typeには必ず uuid または isbn のいずれかを指定してください。


タイトル titles

  • 必須

本のタイトルを指定します。

複数のタイトルを指定したり、種別を指定することもできますが、ほとんどのEPUBの閲覧ソフト(リーディングシステム)は複雑な書誌情報を表示することができないので、現時点ではあまり効果は期待できません。シンプルに書くのがよいでしょう。

シンプルにタイトルのみを指定した例です。これが一番無難です。

titles:
  - content: 蜘蛛の糸

参考までに、より複雑な指定方法を紹介します。

警告

次に紹介する方法では、複数のタイトルの表示優先度をEPUB 3の仕様に準拠した形で上から順に指定されます。

しかし Apple の iBooks では優先度を無視して最後のタイトルを本棚に表示します。

マルチベンダー対応を目指すならば、利用するのは現実的ではありません。

タイトルとサブタイトルを区別した例です。

titles:
  - content: 私本太平記 あしかが帖
    title-type: expanded
  - content: 私本太平記
    title-type: main
  - content: あしかが帖
    title-type: subtitle

タイトルにシリーズ名と版数を加えた例です。

titles:
  - content: でんでんコンバーター公式マニュアル
    title-type: main
  - content: でんでんプロジェクトマニュアルシリーズ
    title-type: collection
  - content: 第二版
    title-type: edition

作成者 creators

  • 任意

本の作成者を指定します。

複数の作成者を指定したり、役割を指定することもできますが、タイトル同様ほとんどのEPUBの閲覧ソフト(リーディングシステム)は複雑な書誌情報を表示することができないので、現時点ではあまり効果は期待できません。シンプルに書くのがよいでしょう。

シンプルに作成者の名前を指定した例です。

creators:
  - content: 芥川 龍之介

作成者の役割はroleで指定することができます。

複数の作成者と役割を指定した例です。

creators:
  - content: 蒲 松齢
    role: aut
  - content: 田中 貢太郎
    role: trl

次に示すのはroleに指定する値の一例です。

作成者の役割とrole
日本の出版でよく使われる表記対応するroleの値
著者aut
編集edt
監修edt
翻訳trl
イラストill
原著aut
企画・原案cre
写真pht
解説cwt
朗読nrt

貢献者 contributors

  • 任意

作成者ほど重要ではないが、作品に何らかの形で貢献した人や団体の名前は、貢献者contributorsとして記述しておくことができます。

書き方は作成者と同じです。

シンプルに貢献者の名前を指定した例です。

contributors:
  - content: 貢献した人の名前

複数の貢献者と役割を指定した例です。

contributors:
  - content: 貢献した人の名前1
    role: edt
  - content: 貢献した人の名前2
    role: cwt

言語 language

  • 任意

本が使用する言語を指定します。languageの指定がない場合には、日本語を意味する「ja」が指定されたと見做されます。

language: ja

英語ならば「en」、フランス語なら「fr」を指定します。


出版年月日 date

  • 任意

出版年月日を明示するには、半角数字で西暦4桁月2桁日2桁の計8桁の数字を書きます。

次の例は出版年月日が2013年2月14日であることを表しています。

date: 20130214

ページ送り方向 pageDirection

  • 任意

本のページ送り方向はpageDirectionで指定します。「ltr」を指定すると左から右、「rtl」を指定すると右から左になります。

pageDirectionを省略すると、ページ送り方向は閲覧ソフト(リーディングシステム)に委ねることになります。何らかの値を指定しておいたほうが無難です。

次の例はページ送り方向に右から左を指定しています。

pageDirection: rtl

オプション options

でんでんコンバーターの細かな挙動を指定するためのオプションです。

  • 任意

表紙ページをスキップする

Name skipCover
Value <boolean>
Initial true

通常の読み順から表紙ページを除外します。有効にする場合は「true」、無効にする場合は「false」を指定します。初期値は「true」となっており、指定がない場合には有効と見做されます。

特にKindleではEPUB内部の表紙画像とは別に、独自に表紙を表示する機能があります。そのためこの指定を有効にして表紙の重複を回避することを推奨します。

表紙のスキップを有効にした場合でも、ランドマークナビゲーションをサポートするリーディングシステムではナビゲーションを通じて表紙ページにアクセスすることができます。

扉ページの自動生成

Name titlepage
Value <boolean>
Initial false

扉ページを自動生成するには titlepageに「true」、しない場合には「false」を指定します。初期値は「false」となっており、指定がない場合には無効と見做されます。

目次ページの自動生成

Name tocInSpine
Value <boolean>
Initial true

目次ページを自動生成するには tocInSpineに「true」、しない場合には「false」を指定します。初期値は「false」となっており、指定がない場合には無効と見做されます。

表示する目次の階層指定

Name tocDisplayDepth
Value <integer>
Initial 6

目次ページに表示する目次の階層を1〜6の範囲の数値によって指定します。「1」なら第1階層の目次のみ、「6」なら第1〜第6階層までの全ての目次を表示します。アップロードしたテキストが持つ目次階層よりも大きな値を指定しても問題ありません。

初期値は「6」となっており、指定がない場合にはすべての階層の目次が表示されます。

これによって表示されなくなった階層の項目は、視覚的に隠されているだけなのでリーディングシステムの目次機能からは利用することができます。

この指定は tocInSpine が「true」でない場合には意味がありません。

現在の Readium では、非表示にした階層が目次機能からも利用できなくなるバグがあります。

目次ページでのランドマークナビゲーションの表示

Name displayLandmarksNav
Value <boolean>
Initial false

でんでんコンバーターでは読者を表紙、とびら、目次などのページへ案内するナビゲーションを自動的に生成します。このナビゲーションを目次ページに表示するには displayLandmarksNav に「true」、しない場合には「false」を指定します。初期値は「false」となっており、指定がない場合には無効と見做されます。

この指定は tocInSpine が「true」でない場合には意味がありません。

目次ページでの図版一覧の表示

Name displayLoiNav
Value <boolean>
Initial false

図版一覧用ナビゲーションを目次ページに表示するには displayLoiNav に「true」、しない場合には「false」を指定します。初期値は「false」となっており、指定がない場合には無効と見做されます。

この指定は tocInSpine が「true」でない場合には意味がありません。

目次ページでの表一覧の表示

Name displayLotNav
Value <boolean>
Initial false

表一覧用ナビゲーションを目次ページに表示するには displayLotNav に「true」、しない場合には「false」を指定します。初期値は「false」となっており、指定がない場合には無効と見做されます。

この指定は tocInSpine が「true」でない場合には意味がありません。

縦書きにおける縦中横の自動指定

Name autoTcy
Value <boolean>
Initial pageDirectionltrならfalsertlならtrue

縦書きにおいて連続する半角数字を自動的に縦中横にします。有効にする場合は「true」、しない場合には「false」を指定します。初期値はpageDirectionによって異なります。すなわち横書きでは無効、縦書きでは有効です。

また、「!!」「!?」「??」など2桁の半角感嘆符や疑問符も縦中横にします。

処理する桁数はtcyDigitで指定されており、デフォルトで2桁となっています。

縦書きにおける自動縦中横の桁数

Name tcyDigit
Value <integer>
Initial 2

autoTcyが処理の対象にする半角数字の桁数を2以上の数値で指定します。指定しなかった場合の初期値は2です。

縦書きにおける文字の向き自動指定

Name autoTextOrientation
Value <boolean>
Initial true

縦書きにおける特定の文字の向き(正立/横倒し)を自動処理によって明示的に指定します。 この処理を有効にする場合には「true」、しない場合には「false」を指定します。初期値は「true」となっており、指定がない場合には有効になります。

対象となる文字と方向は、【緊デジ制作・参考資料】正立の指定が必要な文字 に準じたものとなります。対象文字はひとつずつ<span>タグで囲まれ、正立する文字にはupright、横倒しになる文字にはsidewaysのクラス名が付与されます。

あらかじめテキストファイルの中で uprightsidewaystcy のいずれかのクラス名が付与されている文字は、自動処理の対象から除外されます。

koboデバイス向け拡張子

Name kepub
Value <boolean>
Initial false

楽天koboのE Inkデバイス向けに拡張子を「.kepub.epub」にするにはkepubに「true」、しない場合には「false」を指定します。初期値は「false」となっており、指定がない場合には無効と見做されます。

アイコンフォントの埋め込み

  • リスクあり
Name fontAwesome
Value <boolean>
Initial false

オープンソースのアイコンフォント Font Awesome をEPUBの中に埋め込みます。これによって、画像を利用することなく様々なアイコンを表示することができます。使い方はこちらを参照してください。埋め込まれるフォーマットはWOFFのみです。

有効にする場合には「true」、しない場合には「false」を指定します。初期値は「false」となっており、指定がない場合には無効になります。

埋め込みフォントやCSS擬似要素に対応していないリーディングシステムでは正しく表示されないリスクがあります。Kindleは文字化けします。KinoppyやSony Readerではアイコンが表示されません。iBooksなどWebKit系は大丈夫です。

自己責任で利用してください。

文を句点ごとにspanで囲む

Name autoSentenceWrap
Value <boolean>
Initial false

テキストを句点「。」毎にspanタグで囲みます。音声をテキストに同期させるEPUBを作る際、日本語や中国語の文章は文を一つずつ読み上げさせる指定が困難です。このオプションを有効にすると、テキストが句点ごとにspanタグで囲まれるので、文を単位とした読み上げ単位の指定が用意になります。このオプションが追加したspanタグはmoというクラス名を持ちます。

falseを指定した場合

<p>これは文です。「括弧付きの文です。」これも文です。</p>

trueを指定した場合

<p><span class="mo">これは文です。</span><span class="mo">「括弧付きの文です。」</span><span class="mo">これも文です。</span></p>

このオプションはでんでんコンバーターが出力したEPUBを、Tobi にインポートして利用するケースを想定しています。

有効にする場合には「true」、しない場合には「false」を指定します。初期値は「false」となっており、指定がない場合には無効になります。

日本語・中国語以外の言語がこのオプションを利用するメリットはありません。

青空文庫のルビ記法を使う

Name aozoraRuby
Value <boolean>
Initial false

でんでんマークダウンのルビ記法の代わりに、青空文庫のルビ記法を使用します。ルビ以外の青空文庫の記法には対応していません。

以下はオプションの記述例です。

options:
  titlepage: false
  tocInSpine: true
  tocDisplayDepth: 6
  displayLandmarksNav: false
  displayLoiNav: false
  displayLotNav: false
  autoTextOrientation: true
  kepub: false
  autoSentenceWrap: false
  fontAwesome: false

iBooks向けオプション ibooks

AppleのiBooks独自の拡張を指定するためのオプションです。

  • 任意

バージョン情報

Name version
Value <number>
Initial

本のバージョン情報です。「1.0」や「1.0.0」のようにピリオドによって区切られた数値を記述します。ピリオドを3つ以上使った番号を指定することはできません。

この情報を記述したEPUBをiBookstoreで販売した場合、出版者が以前よりも大きなバージョン番号を持ったEPUBに更新すると、購入済みの読者にコンテンツのアップデート通知が送信されるようになります。

フォント指定

Name specifiedFonts
Value <boolean>
true

CSSによるフォント指定の有効/無効を制御するためのオプションです。有効にする場合には「true」、無効にする場合は「false」を指定します。

でんでんコンバーターでは指定がなかった場合の初期値を「true」にしています。あえて無効にする時を除き、このパラメータを利用する必要はありません。

ibooks:
  version: 1.0
  specifiedFonts: true