抠丁客 抠丁客
项目
编辑 (2024/8/4)

Pandoc 用户使用指南 - EPUBs

EPUB 元数据

可以通过使用 --epub-metadata 选项来指定 EPUB 元数据，但如果源文档是 Markdown，则最好使用 YAML 元数据块。下面是一个示例：

---
title:
  - type: main
    text: 我的书
  - type: subtitle
    text: 对元数据的调查
creator:
  - role: author
    text: 约翰·史密斯
  - role: editor
    text: 莎拉·琼斯
identifier:
  - scheme: DOI
    text: doi:10.234234.234/33
publisher: 我的出版社
rights: © 2007 约翰·史密斯, CC BY-NC
ibooks:
  version: 1.3.4
YAML

以下是被识别的字段：

  • identifier

    可以是字符串值或具有字段 text 和 scheme 的对象。scheme 的有效值为 ISBN-10, GTIN-13, UPC, ISMN-10, DOI, LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC, ISMN-13, ISBN-A, JP, OLCC。

  • title

    可以是字符串值，或具有字段 file-as 和 type 的对象，或此类对象的列表。type 的有效值为 main, subtitle, short, collection, edition, extended。

  • creator

    可以是字符串值，或具有字段 role, file-as 和 text 的对象，或此类对象的列表。role 的有效值为 MARC relators，但 pandoc 将尝试将人类可读版本（如 "作者" 和 "编辑"）转换为相应的 marc relators。

  • contributor

    与 creator 相同的格式。

  • date

    格式为 YYYY-MM-DD 的字符串值。（仅需要年份。）pandoc 将尝试转换其他常见日期格式。

  • lang (或遗留: language)

    格式为 BCP 47 的字符串值。如果没有指定任何内容，pandoc 将默认使用本地语言。

  • subject

    可以是字符串值，或具有字段 text, authority, 和 term 的对象，或此类对象的列表。authority 的有效值为 保留的权威值 (AAT, BIC, BISAC, CLC, DDC, CLIL, EuroVoc, MEDTOP, LCSH, NDC, Thema, UDC 和 WGS) 或标识自定义方案的绝对 IRI。term 的有效值由该方案定义。

  • description

    字符串值。

  • type`

    字符串值。

  • format

    字符串值。

  • relation

    字符串值。

  • coverage

    字符串值。

  • rights

    字符串值。

  • belongs-to-collection

    字符串值。标识 EPUB 出版物所属集合的名称。

  • group-position

    group-position 字段指示 EPUB 出版物相对于属于同一 belongs-to-collection 字段的其他作品的数值位置。

  • cover-image

    字符串值（封面图片路径）。

  • css (或遗留: stylesheet)

    字符串值（CSS 样式表路径）。

  • page-progression-direction

    ltr 或 rtl。指定 spine 元素 的 page-progression-direction 属性。

  • accessModes

    字符串数组 (schema)。默认为 ["textual"]。

  • accessModeSufficient

    字符串数组 (schema)。默认为 ["textual"]。

  • accessibilityHazards

    一个字符串数组 (schema)。默认值为 ["none"]。

  • accessibilityFeatures

    一个字符串数组 (模式)。默认值为:

    • "alternativeText"
    • "readingOrder"
    • "structuralNavigation"
    • "tableOfContents"

  • accessibilitySummary

    一个字符串值。

  • ibooks

    iBooks 特定元数据，包含以下字段：

    • version:（字符串）
    • specified-fonts: true|false（默认 false）
    • ipad-orientation-lock: portrait-only|landscape-only
    • iphone-orientation-lock: portrait-only|landscape-only
    • binding: true|false（默认 true）
    • scroll-axis: vertical|horizontal|default

epub:type 属性

对于 epub3 输出，您可以使用 epub:type 属性标记对应于 EPUB 章节的标题。例如，要将属性设置为 prologue，可以使用以下 Markdown：

# 我的章节 {epub:type=prologue}
Plain text

这将生成如下结果：

<body epub:type="frontmatter">
  <section epub:type="prologue">
    <h1>我的章节</h1>
Plain text

Pandoc 将输出 <body epub:type="bodymatter">，除非您使用了以下值之一，在这种情况下，将输出 frontmatter 或 backmatter。

epub:type 的第一个部分 epub:type 的正文
prologue frontmatter
abstract frontmatter
acknowledgments frontmatter
copyright-page frontmatter
dedication frontmatter
credits frontmatter
keywords frontmatter
imprint frontmatter
contributors frontmatter
other-credits frontmatter
errata frontmatter
revision-history frontmatter
titlepage frontmatter
halftitlepage frontmatter
seriespage frontmatter
foreword frontmatter
preface frontmatter
frontispiece frontmatter
appendix backmatter
colophon backmatter
bibliography backmatter
index backmatter

链接媒体

默认情况下，pandoc 将下载任何 <img>、<audio>、<video> 或 <source> 元素引用的媒体，这些元素存在于生成的 EPUB 中，并将其包含在 EPUB 容器中，从而生成一个完全自包含的 EPUB。如果您希望链接到外部媒体资源，请在源文件中使用原始 HTML 并向具有 src 属性的标签添加 data-external="1"。例如：

<audio controls="1">
    <source src="https://example.com/music/toccata.mp3"
            data-external="1" type="audio/mpeg">
    </source>
</audio>
HTML

如果输入格式已经是 HTML，则 data-external="1" 对于 <img> 元素将按预期工作。类似地，对于 Markdown，可以通过 `# Pandoc 用户使用指南 - EPUBs

EPUB 元数据

可以通过使用 --epub-metadata 选项来指定 EPUB 元数据，但如果源文档是 Markdown，则最好使用 YAML 元数据块。下面是一个示例：

---
title:
  - type: main
    text: 我的书
  - type: subtitle
    text: 对元数据的调查
creator:
  - role: author
    text: 约翰·史密斯
  - role: editor
    text: 莎拉·琼斯
identifier:
  - scheme: DOI
    text: doi:10.234234.234/33
publisher: 我的出版社
rights: © 2007 约翰·史密斯, CC BY-NC
ibooks:
  version: 1.3.4
YAML

以下是被识别的字段：

  • identifier

    可以是字符串值或具有字段 text 和 scheme 的对象。scheme 的有效值为 ISBN-10, GTIN-13, UPC, ISMN-10, DOI, LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC, ISMN-13, ISBN-A, JP, OLCC。

  • title

    可以是字符串值，或具有字段 file-as 和 type 的对象，或此类对象的列表。type 的有效值为 main, subtitle, short, collection, edition, extended。

  • creator

    可以是字符串值，或具有字段 role, file-as 和 text 的对象，或此类对象的列表。role 的有效值为 MARC relators，但 pandoc 将尝试将人类可读版本（如 "作者" 和 "编辑"）转换为相应的 marc relators。

  • contributor

    与 creator 相同的格式。

  • date

    格式为 YYYY-MM-DD 的字符串值。（仅需要年份。）pandoc 将尝试转换其他常见日期格式。

  • lang (或遗留: language)

    格式为 BCP 47 的字符串值。如果没有指定任何内容，pandoc 将默认使用本地语言。

  • subject

    可以是字符串值，或具有字段 text, authority, 和 term 的对象，或此类对象的列表。authority 的有效值为 保留的权威值 (AAT, BIC, BISAC, CLC, DDC, CLIL, EuroVoc, MEDTOP, LCSH, NDC, Thema, UDC 和 WGS) 或标识自定义方案的绝对 IRI。term 的有效值由该方案定义。

  • description

    字符串值。

  • type`

    字符串值。

  • format

    字符串值。

  • relation

    字符串值。

  • coverage

    字符串值。

  • rights

    字符串值。

  • belongs-to-collection

    字符串值。标识 EPUB 出版物所属集合的名称。

  • group-position

    group-position 字段指示 EPUB 出版物相对于属于同一 belongs-to-collection 字段的其他作品的数值位置。

  • cover-image

    字符串值（封面图片路径）。

  • css (或遗留: stylesheet)

    字符串值（CSS 样式表路径）。

  • page-progression-direction

    ltr 或 rtl。指定 spine 元素 的 page-progression-direction 属性。

  • accessModes

    字符串数组 (schema)。默认为 ["textual"]。

  • accessModeSufficient

    字符串数组 (schema)。默认为 ["textual"]。

  • accessibilityHazards

    一个字符串数组 (schema)。默认值为 ["none"]。

  • accessibilityFeatures

    一个字符串数组 (模式)。默认值为:

    • "alternativeText"
    • "readingOrder"
    • "structuralNavigation"
    • "tableOfContents"

  • accessibilitySummary

    一个字符串值。

  • ibooks

    iBooks 特定元数据，包含以下字段：

    • version:（字符串）
    • specified-fonts: true|false（默认 false）
    • ipad-orientation-lock: portrait-only|landscape-only
    • iphone-orientation-lock: portrait-only|landscape-only
    • binding: true|false（默认 true）
    • scroll-axis: vertical|horizontal|default

epub:type 属性

对于 epub3 输出，您可以使用 epub:type 属性标记对应于 EPUB 章节的标题。例如，要将属性设置为 prologue，可以使用以下 Markdown：

# 我的章节 {epub:type=prologue}
Plain text

这将生成如下结果：

<body epub:type="frontmatter">
  <section epub:type="prologue">
    <h1>我的章节</h1>
Plain text

Pandoc 将输出 <body epub:type="bodymatter">，除非您使用了以下值之一，在这种情况下，将输出 frontmatter 或 backmatter。

epub:type 的第一个部分 epub:type 的正文
prologue frontmatter
abstract frontmatter
acknowledgments frontmatter
copyright-page frontmatter
dedication frontmatter
credits frontmatter
keywords frontmatter
imprint frontmatter
contributors frontmatter
other-credits frontmatter
errata frontmatter
revision-history frontmatter
titlepage frontmatter
halftitlepage frontmatter
seriespage frontmatter
foreword frontmatter
preface frontmatter
frontispiece frontmatter
appendix backmatter
colophon backmatter
bibliography backmatter
index backmatter

链接媒体

默认情况下，pandoc 将下载任何 <img>、<audio>、<video> 或 <source> 元素引用的媒体，这些元素存在于生成的 EPUB 中，并将其包含在 EPUB 容器中，从而生成一个完全自包含的 EPUB。如果您希望链接到外部媒体资源，请在源文件中使用原始 HTML 并向具有 src 属性的标签添加 data-external="1"。例如：

<audio controls="1">
    <source src="https://example.com/music/toccata.mp3"
            data-external="1" type="audio/mpeg">
    </source>
</audio>
HTML

如果输入格式已经是 HTML，则 data-external="1" 对于 <img> 元素将按预期工作。类似地，对于 Markdown，可以通过 ![img](url){external=1} 声明外部图像。请注意，这只对图像有效；其他媒体元素在 pandoc 的抽象语法树中没有原生表示，并需要使用原始 HTML。

EPUB 样式

默认情况下，pandoc 将包含其 epub.css 数据文件中的一些基本样式。（要查看此文件，请使用 pandoc --print-default-data-file epub.css。）要使用不同的 CSS 文件，请使用 --css 命令行选项。还定义了一些内联样式；这些对于正确格式化 pandoc 的 HTML 输出至关重要。

可以设置 document-css 变量，如果希望使用 pandoc 默认 HTML 模板中更具观点性的样式（在这种情况下，可以使用 HTML 变量 中定义的变量来微调样式）。

在本文档中