hi-folks / ibis-next
从Markdown创建EPUB和PDF电子书
Requires
- php: ^8.2
- ext-ctype: *
- ext-dom: *
- ext-filter: *
- ext-gd: *
- ext-json: *
- ext-mbstring: *
- ext-zlib: *
- hi-folks/phpepub: ^1.0.0
- illuminate/filesystem: ^10.0|^11.0
- illuminate/support: ^10.0|^11.0
- mpdf/mpdf: ^8.0
- spatie/commonmark-highlighter: ^3.0
- symfony/console: ^6.0|^7.0
- symfony/yaml: ^6.0|^7.0
Requires (Dev)
- laravel/pint: ^1.2
- pestphp/pest: ^3.0
- phpstan/phpstan: ^1.10
- rector/rector: ^1
- symfony/var-dumper: ^6.0|^7.0
This package is auto-updated.
Last update: 2024-09-21 07:16:29 UTC
README
使用Markdown创建电子书
Ibis Next是一个开源工具,专为专注于内容创作的电子书制作者开发。Ibis Next支持Markdown格式编写,并能生成PDF、EPUB或HTML格式的电子书。该工具旨在简化电子书创建过程,使作者能够专注于内容创作,同时高效地将内容转换为精美的电子书。
Ibis Next是什么?
Ibis Next是一个基于PHP的工具,简化了整个电子书创建过程。利用Markdown的力量,它使用户能够专注于内容创作,同时自动化生成高质量电子书的复杂性。无论您是经验丰富的作者、技术作家,还是第一次涉足电子书创建领域的人,Ibis Next都旨在使这个过程无缝且高效。
主要功能
- Markdown:使用Markdown的简洁性和多功能性编写内容。
- 自动生成:使用
ibis-next pdf
命令或ibis-next epub
或ibis-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.3、Laravel 11、Symfony 7、Commonmark 2和其他依赖项升级的过程。使用Ibis Next,我们还添加了生成EPUB格式和HTML格式的支持。因此,使用Ibis Next,您可以创建Markdown文件并将它们导出为PDF、EPUB和HTML,以便与您的设备和软件更好地兼容。
安装
在开始之前,请确保您的系统已安装PHP 8.1或更高版本,并确保在您的php.ini
文件中启用了gd扩展。
在本地安装ibis-next
要快速开始本地构建您的电子书,请按照以下步骤操作
如果您想快速开始构建电子书,您可以
- 使用
mkdir
命令创建一个新的空目录,并导航到该目录
mkdir my-first-ebook
cd my-first-ebook
- 使用Composer安装Ibis Next
composer require hi-folks/ibis-next
-
安装完成后,您将在
vendor/
目录中找到您的工具(vendor/bin/ibis-next
)。 -
在特定目录中本地启动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文档的定义:旁注(也称为“警告”或“提示”)有助于在页面的主要内容旁边显示次要信息。
Ibis Next提供了一种定制的Markdown语法,专门用于展示旁注。为了区分旁注块,使用一组三重冒号:::
包围您的内容,指定类型为note
、tip
、caution
或danger
。
虽然您可以在旁注内嵌套其他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也支持另一种引用的语法。我建议使用旁注块而不是这些(已弃用)的引用。可以添加三种引用:quote
、warning
和notice
。
>{quote} This is a quote. >{warning} This is a warning. >{notice} This is a notice.
使用图片
图片可以通过两种不同的方式添加到Markdown中
- 使用远程图片

- 使用相对路径,在这种情况下,路径是相对于内容目录的,您在其中拥有Markdown文件(默认为
./content/
)

它也可以与绝对路径一起使用,但我不建议使用此选项,因为它与您的特定机器紧密相关。
添加封面图片
要使用封面图片,请在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.
使用字体
编辑您的/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} 
生成电子书
生成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.md
、artisan.md
和console-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文件。
鸣谢
- Mohamed Said,原始Ibis项目的作者
- Roberto Butti,Ibis Next项目的更新和分支的作者
- 所有贡献者
许可协议
MIT许可协议(MIT)。请参阅许可文件以获取更多信息。