hi-folks/ibis-next

从Markdown创建EPUB和PDF电子书

v2.0.2 2024-09-14 08:03 UTC

README

Ibis Next cover

使用Markdown创建电子书

Ibis Next是一个开源工具,专为专注于内容创作的电子书制作者开发。Ibis Next支持Markdown格式编写,并能生成PDF、EPUB或HTML格式的电子书。该工具旨在简化电子书创建过程,使作者能够专注于内容创作,同时高效地将内容转换为精美的电子书。

Ibis Next是什么?

Ibis Next是一个基于PHP的工具,简化了整个电子书创建过程。利用Markdown的力量,它使用户能够专注于内容创作,同时自动化生成高质量电子书的复杂性。无论您是经验丰富的作者、技术作家,还是第一次涉足电子书创建领域的人,Ibis Next都旨在使这个过程无缝且高效。

主要功能

  • Markdown:使用Markdown的简洁性和多功能性编写内容。
  • 自动生成:使用ibis-next pdf命令或ibis-next epubibis-next html命令,轻松通过单一命令创建PDF、EPUB或HTML文件。
  • 美观性:使用自定义封面图片、可点击的自动生成目录以及代码语法高亮来创建您的电子书。
  • 主题选项:在两种视觉上吸引人的主题(浅色和深色)之间选择(主题支持适用于PDF)。

为什么选择Ibis Next?

Ibis Next是一个强大的工具,可以轻松创建EPUB、PDF和HTML格式的数字书籍(电子书)。使用Ibis Next,作家可以专注于内容创作,无需担心格式问题。内容以Markdown格式编写,具有简单性和灵活性。

Ibis Next无缝处理转换过程,确保从Markdown到正确的EPUB、PDF和HTML格式的无障碍过渡。采用Markdown简化了写作过程,并提高了协作和编辑的便利性,是寻求效率和专注于内容创作的作者的理想选择。

准备好用Ibis Next彻底改变您的电子书创建过程吧!

Mohamed Said创建了Ibis项目。Ibis项目的源代码位于https://github.com/themsaid/ibis。感谢Mohamed创建这个工具。

我们分叉了仓库以加快支持PHP 8.2、PHP 8.3Laravel 11Symfony 7Commonmark 2和其他依赖项升级的过程。使用Ibis Next,我们还添加了生成EPUB格式HTML格式的支持。因此,使用Ibis Next,您可以创建Markdown文件并将它们导出为PDF、EPUB和HTML,以便与您的设备和软件更好地兼容。

安装

在开始之前,请确保您的系统已安装PHP 8.1或更高版本,并确保在您的php.ini文件中启用了gd扩展。

在本地安装ibis-next

要快速开始本地构建您的电子书,请按照以下步骤操作

如果您想快速开始构建电子书,您可以

  1. 使用mkdir命令创建一个新的空目录,并导航到该目录
mkdir my-first-ebook
cd my-first-ebook
  1. 使用Composer安装Ibis Next
composer require hi-folks/ibis-next
  1. 安装完成后,您将在vendor/目录中找到您的工具(vendor/bin/ibis-next)。

  2. 在特定目录中本地启动Ibis Next时,请使用以下命令

./vendor/bin/ibis-next list

全局安装ibis-next

如果您希望全局安装composer包,请使用global选项与composer require命令结合使用

composer global require hi-folks/ibis-next

当Ibis Next全局安装后,您可以使用ibis-next命令启动和运行它

ibis-next list

初始化电子书

要开始,请使用init命令初始化您的项目目录。此命令会自动创建必要的配置文件、资产文件夹以及Markdown文件的内容文件夹。

本地安装的Ibis Next

如果您已本地安装Ibis Next,请从您的项目目录中运行init命令

./vendor/bin/ibis-next init

全局安装的Ibis Next

如果您已全局安装Ibis Next,请在您想要创建电子书的新空目录中运行init命令

ibis-next init

ibis-next init命令将生成以下文件和目录

  • assets目录,其中包含用于构建PDF和EPUB文件的主题文件。由于该过程涉及将内容临时转换为HTML的中介步骤,因此主题文件是HTML和CSS格式,以确保输出文件的正确样式。
  • assets/fonts目录,您可以在此处下载和使用您的TrueType字体(TTF)文件。
  • assets/cover.jpg,这是一张示例书封图片。
  • assets/images目录,包含示例书中使用的示例图片。
  • content目录,其中包含一些示例Markdown文件。您可以编辑这些文件或创建新的文件。
  • ibis.php文件,其中包含Ibis Next的配置。

通过编辑ibis.php配置文件来配置您的电子书。

设置特定目录

如果您希望初始化不同的空目录(不是当前目录),请使用-d选项与init命令。例如

ibis-next init -d ../some-other-directory

这对于您只想安装Ibis Next一次,同时在单独的目录中管理多本书非常有用。

编写您的电子书

init命令将在content文件夹中创建示例.md文件。您可以探索这些文件以了解如何编写您的书籍。此示例内容取自Roberto Butti的Ibis Next: 使用Markdown创建电子书

content目录内,您可以编写多个.md文件。Ibis使用标题将书籍分为部分和章节

# Part 1

`<h1>` tags define the start of a part. A separate PDF page will be generated to print the part title and any content below.

## Chapter 1

`<h2>` tags define the start of a chapter. A chapter starts on a new page always.

### Starting with Ibis

`<h3>` tags define different titles inside a chapter.

添加旁注

受优秀的Astro Starlight创建技术文档工具的启发,我们支持旁注块。根据Astro Starlight文档的定义:旁注(也称为“警告”或“提示”)有助于在页面的主要内容旁边显示次要信息。

Aside block examples

Ibis Next提供了一种定制的Markdown语法,专门用于展示旁注。为了区分旁注块,使用一组三重冒号:::包围您的内容,指定类型为notetipcautiondanger

虽然您可以在旁注内嵌套其他Markdown内容类型,但建议使用旁注来展示内容中的简短部分。

:::note
**Ibis Next** is an open-source tool, and you can contribute to the project by joining the [Ibis Next GitHub repository](https://github.com/Hi-Folks/ibis-next).
:::

:::warning
**Ibis Next** is an open-source tool, and you can contribute to the project by joining the [Ibis Next GitHub repository](https://github.com/Hi-Folks/ibis-next).
:::

:::tip
**Ibis Next** is an open-source tool, and you can contribute to the project by joining the [Ibis Next GitHub repository](https://github.com/Hi-Folks/ibis-next).
:::

:::danger
**Ibis Next** is an open-source tool, and you can contribute to the project by joining the [Ibis Next GitHub repository](https://github.com/Hi-Folks/ibis-next).
:::

您还可以使用方括号[你的标题]自定义旁注块的标题

:::tip[My two cents]
I want to give you some advice: use **Ibis Next** to create your e-books.
:::

在上面的示例中,使用了旁注类型"tip"(:::tip),自定义标题为"我的看法"([我的看法]),旁注块的內容可以包含使用经典Markdown标记格式化的文本。

添加不同的引用

出于历史原因,Ibis Next也支持另一种引用的语法。我建议使用旁注块而不是这些(已弃用)的引用。可以添加三种引用:quotewarningnotice

>{quote} This is a quote.

>{warning} This is a warning.

>{notice} This is a notice.

使用图片

图片可以通过两种不同的方式添加到Markdown中

  1. 使用远程图片
![Ibis Next Cover Image](https://raw.githubusercontent.com/hi-folks/ibis-next/main/art/ibis-next-cover.png)
  1. 使用相对路径,在这种情况下,路径是相对于内容目录的,您在其中拥有Markdown文件(默认为./content/
![Ibis Next Cover Image](../assets/images/ibis-next-cover.png)

它也可以与绝对路径一起使用,但我不建议使用此选项,因为它与您的特定机器紧密相关。

添加封面图片

要使用封面图片,请在assets/目录下添加一个cover.jpg文件(或者如果您更喜欢基于HTML的封面页,则可以添加一个cover.html文件)。如果您不想要封面图片,请删除这些文件。如果您的封面是PNG格式,您可以将文件存储在assets/目录中,然后在ibis.php文件中,您可以调整cover配置,设置封面文件名,例如:

    'cover' => [
        'position' => 'position: absolute; left:0; right: 0; top: -.2; bottom: 0;',
        'dimensions' => 'width: 210mm; height: 297mm; margin: 0;',
        'image' => 'cover.png',
    ],

封面图片可以使用WebP、PNG或JPG格式。

设置页面标题

在Ibis Next中,您可以为您页面设置自定义标题。为此,导航到ibis.php配置文件,并找到header参数。在ibis.php文件中,您可以指定您想要的标题,如下所示:

     /**
      * CSS inline style for the page header.
      * If you want to skip header, comment the line
      */
     'header' => 'font-style: italic; text-align: right; border-bottom: solid    1px #808080;',

这允许您根据您的偏好个性化标题内容。您可以根据具体要求修改单引号内的值。header参数的值是要应用于页面标题的CSS内联样式。如果您不需要或不想在电子书中有页面标题,可以删除header参数。

如果您想为每个部分的页面标题自定义文本,在markdown文件中,您可以在frontmatter部分添加title参数

---
title: My Title
---

## My Section Title
This is an example.

Setting the page header

使用字体

编辑您的/ibis.php配置文件,以定义从/assets/fonts目录中加载的字体文件。之后,您可以在主题中(/assets/theme-light.html/assets/theme-dark.html)使用这些定义的字体。

设置属性

考虑到将Markdown转换为PDF的过程涉及生成HTML,您可以应用CSS样式来设置特定的类样式。要向Markdown中的元素添加CSS类(或任何属性),您可以使用属性语法。

例如,要向图片添加CSS类,考虑Markdown转换为HTML时会产生一个包含img元素的p元素。您可以定义如下CSS样式:

.image-container {
    text-align: center; /* Center the content inside the paragraph */
    padding: 20px; /* Optional: Add padding around the paragraph */
    background-color: #f5f5f5; /* Optional: Set a background color */
    border-radius: 10px; /* Optional: Add rounded corners */
}

.image-container img {
    max-width: 80vw; /* Set the image to 80% of the viewport width */
    height: auto; /* Maintain the aspect ratio */
    display: inline-block; /* Ensure the image behaves like an inline-block element */
}

然后,当您需要使用image-container CSS类在Markdown中嵌入图片时,可以使用以下语法:

{#id-cover-001 .image-container}
![Ibis Next Cover Image](./content/images/ibis-next-cover.png)

生成电子书

生成PDF电子书

要使用Ibis Next生成PDF电子书,运行以下命令:

ibis-next pdf

Ibis Next默认按字母顺序解析文件,并将PDF文件存储在export目录中。

如果您更喜欢使用暗色主题的PDF,使用以下命令:

ibis-next pdf dark

使用不同目录的内容

如果您的Markdown文件(内容)存储在默认的./content/以外的目录中,请使用--content选项指定内容目录

ibis-next pdf --content=./your-content-directory

或者,使用较短的-c选项

ibis-next pdf -c ./your-content-directory

生成EPUB电子书

要从Markdown内容自动生成EPUB文件,使用epub命令

ibis-next epub

Ibis Next将按字母顺序解析文件,并将EPUB文件存储在export目录中。您可以将EPUB文件轻松上传或传输到您的手机、平板电脑或Kindle设备。

默认情况下,使用assets/style.css文件生成EPUB文件。

使用不同的assets/config目录生成电子书

如果您管理多本书,您可以指定工作目录、资产文件夹的位置以及ibis.php配置文件的位置。使用-d选项定义工作目录的路径

ibis-next epub -c ../your-dir-with-markdown-files -d ../myibisbook

您可以将-c选项(用于定义内容目录)和-d选项(用于定义工作目录)结合使用。

您可以在内容目录的子文件夹中组织Markdown文件。

生成HTML电子书

要自动从Markdown内容生成HTML文件,使用html命令

ibis-next html

Ibis Next将按字母顺序解析文件,并将HTML文件存储在export目录中。您可以使用任何浏览器轻松阅读HTML文件。

默认情况下,使用assets/theme-html.html文件生成HTML文件。

Markdown文件列表配置

ibis.php配置文件中的md_file_list配置允许您指定在生成PDF、EPUB或HTML输出时应该包含哪些Markdown文件。默认情况下,如果未设置md_file_list,将使用内容目录中的所有Markdown文件。

用法

如果您想限制文件到特定的子集,可以定义如下包含文件名(包括扩展名)的md_file_list数组

'md_file_list' => [
    'routing.md',
    'artisan.md',
    'console-tests.md',
],

在此示例中,只有来自内容目录的routing.mdartisan.mdconsole-tests.md将被处理以生成PDF、EPUB或HTML。

注意

  • 默认行为:如果未指定md_file_list,则将包含内容目录中的所有Markdown文件。
  • 文件路径:确保在md_file_list中列出的文件名包含正确的扩展名,并且位于内容目录中。

此配置提供在选择特定文件以满足输出需求方面的灵活性,使您能够根据需要定制内容。

例如,如果您需要构建您书籍的样本,可以使用md_file_list

生成样本

对于生成样本,建议评估使用md_file_list配置。由于历史原因,也提供了样本命令,但它仅适用于PDF文件。

ibis-next sample

ibis-next sample dark

此命令将使用ibis-next build命令生成的文件来从您的PDF电子书中生成样本。您可以通过更新/ibis.php文件来配置要包含在样本中的页面。

反馈

如果您正在使用或正在评估使用Ibis Next创建您的下一本电子书,请告知我。我可以通过演示工具、帮助配置或评估功能请求来支持您。

开发

如果您想为这个开源项目做出贡献,可以阅读项目根目录下的CONTRIBUTING.md文件。

鸣谢

许可协议

MIT许可协议(MIT)。请参阅许可文件以获取更多信息。