Markdownから目次、章、カバー付きEPUBを1つのAPI呼び出しで生成

出版産業は、書籍製作のための複雑なツール チェーンを構築することに何十年も費やしました。原稿は、ワープロプロセッサからページレイアウト ソフトウェアを通じてPDF生成器から印刷前のファイルまで、複数の専門家と各段階で複数のソフトウェア ライセンスを含むパイプラインを通して移動されました。電子書籍が登場したとき、パイプラインは単純化されるのではなく、複雑さが増しました。同じ原稿が、印刷前のPDFと反射可能なEPUBの両方を作成する必要がありました。コンテンツがどのように提示されるべきかについて、根本的に異なる哲学を持つ形式です。印刷形式はすべてを所定の位置に固定します。電子書籍形式はすべてを流れるままにします。単一のソースからの両方の生成は、従来の出版ツール チェーンがパッチワーク キルトのすべての優雅さで処理する問題です。

自費出版する著者は、従来の出版社が提供する制度的サポートなしにこのツール チェーンの複雑さに直面しています。原稿はWord文書またはGoogle Docとして存在します。適切にフォーマットされたEPUBへの変換には、専門的な電子書籍制作ソフトウェア（Calibre、Sigil、Vellum）を学ぶか、プロジェクトごとに料金を請求するフォーマッターを支払うかが必要です。本に創造的な価値を追加しない書式設定手順は、原稿の完成と読者への公開の間のボトルネックになります。複数の本を出版する著者の場合、この書式設定ステップの累積コストと時間は重要であり、完全に予測可能であり、自動化の理想的な候補となります。

Ebooks APIは、全体的な変換プロセスを単一のAPI呼び出しに削減します。Markdownで本を書いてください。これは、任意のテキストエディタが作成でき、どの著者も10分で学習できる形式です。メタデータと オプションのカバー画像とともにMarkdownコンテンツを送信します。構造化された目次、適切に区切られた章、埋め込まれたカバー画像、および電子書籍の小売業者とライブラリが必要とするすべてのメタデータを備えた専門的なEPUBファイルを受け取ります。1つの入力、1つの呼び出し、1つの出力。HTTPリクエストに圧縮された全体的な出版ツール チェーン。

Markdownが本の執筆の理想的な形式である理由

Markdownのリッチテキストエディタに慣れた著者への本の執筆への適切性は、すぐには明らかではありません。この形式は、WordやGoogle Docsの書式付きビューと比較して、シンプルに見え、ほぼ原始的です。しかし、この見かけ上の単純さは、正確に長い形式の書き込みの強さです。Markdownはコンテンツとプレゼンテーションを完全に分離します。つまり、著者は、どのように見えるかによって気を散らしたり制限されたりすることなく、彼らが何を言っているかに焦点を当てています。プレゼンテーション の決定は、変換プロセス中に後で行われます。原稿に触れることなく、一貫して適用され、全体的に変更できます。

Markdownのチャプターの見出しはハッシュシンボルで マークされています。単一のハッシュは本のタイトルを示します。ダブルハッシュはチャプターのタイトルを示します。トリプルハッシュは、章内のセクション見出しを示します。この階層構造はEPUBのナビゲーション構造に直接マップされます。チャプターのタイトルは目次のエントリになり、セクションの見出しはサブエントリになり、本のタイトルはトップレベルのナビゲーション要素になります。著者は見出しをマークするという単純な行為を通じて本の構造を作成し、APIはその構造をEPUBのナビゲーション フレームワークに自動的に変換します。

段落は空白行で区切られます。強調はアスタリスクでマークされます。ブロック引用符は角括弧でマークされます。リンクは角括弧と括弧でマークされています。これらのMarkdown慣例のそれぞれは、EPUBの内部HTMLの直接的な同等物を持っており、変換は決定的です。同じMarkdown入力は常に同じEPUB構造を生成します。この予測可能性は、改訂版または更新版を発行する著者にとって重要です。Markdownへの変更によって、EPUB内での対応する正確な変更が生成され、書式設定の副作用が導入されるためです。

Markdownファイルの移植性は、もう1つの重要な利点です。Markdownで書かれた原稿は、任意のツールで任意のオペレーティングシステムで開いて、編集して、バージョン管理できるプレーンテキストファイルです。特定のワープロプロセッサバージョンに固定されておらず、アクセスするために特定のソフトウェアライセンスを必要とせず、ソフトウェア形式が進化するにつれて時間の経過に伴って低下しません。今日書かれたMarkdown原稿は、10年または20年後に完全に同じ形式で読めます。これは、独占的なドキュメント形式では言えません。著者が彼らの著作を長期間にわたって維持および更新することを計画している場合、このフォーマットの長寿命は有意義なメリットです。

メタデータとEPUBを専門的にするもの

専門的なEPUBファイルには、本のコンテンツ以上が含まれます。本を配布、カタログ、および表示するシステムに本を説明するメタデータが含まれています。タイトル、著者、出版社、言語、公開日、ISBN、説明、および件名カテゴリはすべて、電子書籍小売業者、ライブラリシステム、および読書アプリケーションが本を適切にカタログ化して表示するために使用される構造化メタデータとしてEPUBファイルに埋め込まれます。

APIはMarkdownコンテンツとともにこのメタデータを受け入れ、EPUBメタデータをどのように構造化するかを定義するOPF（Open Packaging Format）仕様に従ってEPUBに埋め込みます。メタデータは単にファイルヘッダーに貼り付けられるだけではなく。EPUBが使用するDublin Coreメタデータ標準に従ってフォーマットされ、適切な要素の種類、属性、および検証ツールと小売プラットフォームが期待する名前空間の宣言があります。適切に構造化されたメタデータを含むEPUBは、Amazon KDP、Apple Books、Kobo、Google Play Books、および他のすべての主要な小売プラットフォームで変更なしで受け入れられます。

カバー画像は、潜在的な読者が小売環境で最初に目にするものであるため、特に重要なメタデータ要素です。APIはカバー画像ファイル（JPEGまたはPNG）を受け入れ、読書アプリケーションがそれを本のカバーとして表示させる適切なマニフェストエントリ、スパイン参照、およびメタデータ宣言でEPUBに埋め込みます。画像は、小売プラットフォームが課すサイズとファイルサイズの要件を満たすために、必要に応じてサイズが変更および最適化され、EPUBが手動の画像処理なしで小売ユーザーが使用できることを保証します。

ISBN埋め込みは、本をグローバルな本の取引インフラストラクチャに接続する識別子であるため、特別な言及に値します。適切に埋め込まれたISBNを含むEPUBは、ライブラリでカタログ化され、小売業者によって追跡され、レビューサイトで参照され、本が議論または販売されている任意の文脈で明確に識別できます。APIは、国際ISBNエージェンシーが指定した形式を使用してEPUBのメタデータにISBNを埋め込み、ISBNを識別およびカタログ管理に使用するシステムとの互換性を保証します。

目次と章の構造

EPUBの目次は、印刷された本の目次とは異なる2つの機能を果たします。印刷された本では、TOCはチャプターのタイトルとページ番号をリストする ページです。EPUBでは、TOCはナビゲーション要素であり、任意の章またはセクションへの直接ジャンプを有効にし、読書アプリケーションのナビゲーションインターフェースで表示されるレンダリングされたページとしてではなく。よく構造化されたEPUB TOCは、よく構造化されたWebサイトがナビゲーション可能であるのと同じ方法で、本を ナビゲーション可能にします。読者は、本全体を順番にスクロールすることなく、任意の章に直接ジャンプできます。

APIはMarkdownコンテンツ内の見出し構造からTOCを生成します。各レベル2の見出し（ダブルハッシュ）は、TOC内の章エントリになります。各レベル3の見出し（トリプルハッシュ）は、親の章の下のサブエントリになります。この2段階のナビゲーション構造は、ナビゲーションインターフェースを過度なサブエントリで圧倒することなく、ほとんどの本に十分な粒度を提供します。TOCは、ナビゲーション要素（EPUB2互換性用のNCXとEPUB3用のNavigation Document）の両方として生成され、本が古いe-readerおよび最新の読書アプリケーションで正しく機能することを保証します。

生成されたEPUBのチャプターの改行は、Markdownのレベル2の見出しに対応しています。各章はe-readerの新しいページで始まり、読者が期待する章間の視覚的な分離を提供します。APIは、e-readerが各章を連続スクロールではなく個別のナビゲーション単位として扱うことを保証するために、適切なXHTMLページの改行とスパインエントリを挿入します。このチャプター分離により、e-readerが読書進度インジケータにチャプタータイトルを表示することもでき、読者が現在読んでいるチャプターと、どのくらい進んでいるかを示します。

複数の章、付録、または前置きセクションを含む部分など、複雑な構造を持つ本の場合、Markdown見出しの階層はこれらの構造に自然に対応しています。レベル1の見出しはパーツを表し、レベル2の見出しはパーツ内の章を表し、レベル3の見出しは章内のセクションを表します。APIはこの階層を忠実にEPUBのナビゲーション構造にマップし、著者が使用するネストのレベルに関係なく、本の組織の論理を反映するTOCを生成します。

1つの呼び出しとAPI要求の外観

EPUBを生成するAPI呼び出しは、Markdownコンテンツ、メタデータフィールド、およびオプションでカバー画像ファイルを含むPOST要求です。Markdownコンテンツは本の本体であり、著者が使用する見出し、段落、およびその他のMarkdown要素でマークアップされています。メタデータフィールドはキーと値のペアです。タイトル、著者、言語、説明、ISBN、公開日、著者が含めたい追加のDublin Coreフィールド。カバー画像が提供されている場合、ファイルの添付ファイルとしてアップロードされます。

応答は、ダウンロード、配布、または小売プラットフォームへのアップロードの準備ができているEPUBファイル自体です。ファイルはEPUB 3仕様に準拠しており、EPUB 2互換性のフォールバックがあり、すべての最新のe-readerおよび読書アプリケーション、ならびに以前の標準のみをサポートする古いデバイスで機能することを保証します。ファイルはエラーなしでEPUB検証（epubcheck）に合格します。これは、ほとんどの小売プラットフォームへの提出の要件であり、構造的な正確性の強い指標です。

複数の本または複数の版を持つ著者の場合、API呼び出しを自動公開パイプラインに統合できます。Markdown原稿はバージョン管理（たとえばGit）に保存され、メタデータは構成ファイルに保存され、新しいバージョンを生成する必要があるときはいつでも、ビルドスクリプトが両方をAPIに送信します。このパイプラインの自動化は、手動のフォーマットワークフローが必要とする時間または日数ではなく、数分で修正、更新、および新しい版を生成して配布できることを意味します。タイプミスの修正には30秒かかります。Markdownを編集し、ビルドスクリプトを実行し、新しいEPUBを小売プラットフォームにアップロードします。

API呼び出しの単純さは、その背後で発生している操作の複雑さを隠しています。APIはMarkdownを解析し、各章のXHTMLコンテンツファイルを生成し、OPFマニフェストとスパインを作成し、NCXとNavigation Documentを生成し、カバー画像を埋め込んで参照し、Dublin CoreおよびEPUB仕様に従ってすべてのメタデータを構造化し、すべてをEPUBコンテナ形式（実際には特別に構造化されたZIPファイル）にパッケージ化し、EPUB仕様に対して結果を検証します。これらの操作のそれぞれは、手動EPUB製造における潜在的な故障ポイントを表し、毎回自動的かつ確実に処理されます。