魔法书项目

该项目仍在朝着1.0.0版本努力,这意味着API正在积极开发中。EPUB和MOBI格式目前还不支持。我们鼓励开发者尝试发布版本并在问题追踪器中报告任何问题。

魔法书项目是一个由纽约大学交互电信项目资助的开源项目。它旨在成为从单一源创建印刷和数字书籍的最佳免费工具。

如果你符合以下条件,这个项目就是为你准备的:

虽然已经存在少量开源出版框架,但很难找到一个既能创建现代、交互式网络书籍,又能导出印刷就绪PDF的灵活框架。

magicbook的大部分功能以插件形式存在,所以如果你在核心功能中找不到特定功能,也许可以在插件列表中找到。

入门

首先安装magicbook包:

npm install magicbook -g

然后运行新项目生成器:

magicbook new myproject

这将为你创建一个非常基础的项目文件夹,其中包含magicbook.json配置文件。现在进入新项目并构建书籍。

cd myproject
magicbook build

你现在在myproject/build目录中有两个构建:一个网站和一个PDF。这当然是一个非常基础的设置。请查阅本README的其余部分了解所有可用功能。

配置

要为你的项目指定配置,magicbook使用项目文件夹中名为magicbook.json的文件。当你运行magicbook build时,将自动检测配置文件。如果你希望自定义配置文件的名称和位置,可以使用--config命令行参数。

magicbook build --config=myfolder/myconfig.json

源文件

你可以用.md、.html或两者来写你的书。magicbook使用一个非常简单的HTML5层,称为HTMLBook,来定义书中的各种元素。这主要意味着使用一些data-type属性来指定章节和部分,非常容易学习。这也使得magicbook能够在生成目录等方面发挥魔力。

用Markdown写作

如果你选择用Markdown写书,magicbook会自动将你的markdown转换为HTMLBook。像下面这样的简单文件...

# 章节标题

## 第1节

### 第2节

...将被转换为以下HTMLBook标记。

<section data-type="chapter">
  <h1>章节标题</h1>
  <section data-type="sect1">
    <h1>第1节</h1>
    <section data-type="sect2"><h2>第2节</h2></section>
  </section>
</section>

用HTML写作

如果你选择用HTML写作,你需要确保使用HTMLBook的data-type属性。如果你不使用它们,magicbook不会出错,但无法生成目录等。

files数组

你可以通过在magicbook.json文件中添加files数组来指定要构建的文件。如果你没有files数组,它会在content/*.md中查找所有markdown文件。

你可以将files属性设置为单个glob。

{
  "files": "content/*.md"
}

你可以将files属性设置为glob数组。

{
  "files": ["content/chapter1/*.md", "content/chapter2/*.md"]
}

使用数组,你还可以指定要构建的每个文件。

{
  "files": [
    "content/first-file.md",
    "content/second-file.md",
    "content/third-file.md"
  ]
}

如果你不使用permalink设置,你的glob结构将决定构建文件夹中的输出路径。如果你的glob使用通配符*,文件夹将在构建文件夹中保留。

如果你使用这种方法,你可以在文件夹和文件名中使用数字来排序文件,因为构建过程将删除文件夹和文件名中的前导数字、破折号和下划线。以下列文件为例:

contents/
  01-first-chapter/
    01-first-file.md
    02-second-file.md

...以及这个配置文件:

{
  "files": ["contents/**/*.md"]
}

...默认情况下将创建一个如下所示的html构建:

build1/
  first-chapter/
    first-file.html
    second-file.html

如果你想对文件夹和文件名有更多控制,请使用permalink设置。

部分

你可以使用特殊的对象语法将文件分组为部分和子部分。以下示例演示了一本包含介绍和两个部分(每个部分包含几个章节)的书。这些部分将自动添加到目录中,并且在使用带有:parts变量的permalinks设置时,标签将用于slug中。

{
  "files": [
    "introduction.md",
    {
      "label": "第1部分",
      "files": ["first-chapter.md", "second-chapter.md"]
    },
    {
      "label": "第2部分",
      "files": ["third-chapter.md", "fourth-chapter.md"]
    }
  ]
}

你还可以有子部分,如下所示:

{
  "files": [
    {
      "label": "部分",
      "files": [
        "first-chapter.md",
        {
          "label": "子部分",
          "files": ["second-chapter.md"]
        }
      ]
    }
  ]
}

如果你向一个部分添加额外的属性，它将作为liquid变量在文件中可访问。以下展示了一个非常简单的用例，其中"Hello"被插入到文件中。

{
  "files" : [
    {
      "label" : "Part",
      "files" : [ ... ],
      "myVariable" : "Hello"
    }
  ]
}

这是我的文件。 {{ part.myVariable }}

构建

你必须在配置中添加一个builds数组，至少定义每个构建的格式。这里有一个简单的例子，展示了将你的书构建成网站的最小配置。

{
  "builds": [{ "format": "html" }]
}

builds数组是一个非常强大的概念，因为它允许你为每个构建指定设置。例如，这里有一本书在HTML和PDF构建中使用了不同的介绍。magicbook中的所有设置都可以指定为全局设置或构建设置。

{
  "builds": [
    {
      "format": "pdf",
      "files": [
        "content/print-introduction.md",
        "content/chapter-1.md",
        "content/chapter-2.md"
      ]
    },
    {
      "format": "html",
      "files": [
        "content/web-introduction.md",
        "content/chapter-1.md",
        "content/chapter-2.md"
      ]
    }
  ]
}

使用builds数组，你可以有几个使用相同格式的构建。这在你想生成一个带有超链接的PDF，和另一个用于打印的不带超链接的PDF时非常有用。

构建目标

destination指定将构建放在哪里。因为你可以有多个构建，默认目标是build/:build，这将在build文件夹内为每个构建创建一个构建文件夹（build/build1，build/build2等）。

你可以在配置文件中更改此设置。

{
  "destination": "my/custom/folder/:build"
}

构建格式

magicbook有以下内置格式。

HTML

html格式将所有源文件保存为单独的.html文件，作为静态网站。

PDF

pdf格式将合并所有源文件，将它们捆绑成一个单一的.html文件，并在格式目标文件夹中生成一个PDF。目前，这个过程使用Prince XML进行PDF生成，因为它是少数几个可以从HTML生成印刷就绪PDF文件的应用之一。你需要一个Prince XML许可证才能在没有水印的情况下使用它。

你可以为Prince XML定义设置。

{
  "prince": {
    "log": "myfile.txt",
    "license": "license.dat",
    "timeout": 300000
  }
}

EPUB（待完成）

MOBI（待完成）

永久链接

你可以使用permalink设置来覆盖默认的glob控制的构建路径。:title字符串的任何出现都将被原始文件名替换，因此以下配置可用于创建"美化"的永久链接。

{
  "permalink": "chapters/:title/index.html"
}

:parts字符串的任何出现都将被文件所属的部分替换，因此如果一个文件属于一个子部分，:parts/:title.html将导致构建文件位于part/sub-part/filename.html。

链接

magicbook可以自动解析交叉引用。如果你在使用Markdown写作，只需在目标文档中创建一个ID：

<a id="mytarget"></a>

...然后从任何文件链接到该ID：

[前往我的目标](#mytarget)

如果你使用HTML写作也是一样的，但你需要让你的链接有一个HTMLBook的data-type属性：

<a href="#mytarget" data-type="xref">前往我的目标</a>

magicbook将根据构建设置自动确定是否需要在href中插入目标文件。

如果你想在打印版的链接文本中插入页码，使用Prince XML和CSS很容易实现。

自动生成的ID

默认情况下，magicbook会在每个带有HTMLBook data-type属性的部分上添加一个自动生成的ID。这在内部用于生成目录。如果你给一个部分添加ID，这个ID将覆盖自动生成的ID。

你可以依赖这些ID进行内部引用，因为它们在文档不变的情况下在构建之间是持久的。但是，如果你改变了部分的顺序，ID也会改变。

脚注

magicbook将自动解析你内容中的Markdown或HTMLBook脚注，并让你能够按照自己的喜好渲染自定义的脚注部分。首先，用Markdown写脚注。

丹麦有500万人口。^[我编的]

...或HTML

<p>
  丹麦有500万人口。<span data-type="footnote">我编的</span>
</p>

然后在你想要编译脚注出现的地方添加一个liquid变量。

{{ footnotes }}

由于liquid模板在markdown转换之前被评估，而脚注是在markdown转换之后编译的，magicbook会在liquid处理过程中首先插入一个占位符字符串，然后在构建过程的后期用名为footnotes.html的特殊include的输出替换这个占位符。要生成脚注，你必须在你的includes文件夹中有这个include。这个include将有权访问以下脚注数组：

[
  {
    id: "fn1",
    label: "脚注文本"
  }
]

所有用magicbook new创建的项目都会有一个footnotes.html include，这是一个很好的参考，可以看到可能的操作。

图片

当你想插入一张图片时，只需在你的书中创建一个名为images的文件夹，将你的图片保存到这个文件夹中，并使用你的图片名称创建一个图片标签。

对于保存在images/myimage.jpg的图片，以下将是适当的标记。

![这是一张图片](https://raw.githubusercontent.com/magicbookproject/magicbook/main/myimage.jpg)

或

<img src="https://raw.githubusercontent.com/magicbookproject/magicbook/main/myimage.jpg" alt="这是一张图片" />

在构建过程中，magicbook将把位于images中的所有文件转移到每个构建的asset文件夹，并适当替换图片src属性。

源文件

你可以通过提供一个 glob 数组来更改 magicbook 查找图像的位置，就像通用的 files 数组一样。默认模式是 images/**/*.*。

{
  "images": {
    "files": "custom/images/folder/**/*.jpg"
  }
}

目标文件夹

也可以控制图像在构建中的存储位置。你可以使用 destination 属性指定自定义目标文件夹。默认值为 assets。

{
  "images": {
    "destination": "custom/assets/folder"
  }
}

摘要

digest 选项会在文件名中添加图像内容的 md5 校验和，以便你可以为生产网站设置长时间的缓存头。

{
  "images": {
    "digest": true
  }
}

色彩空间

你可以指定输出图像的 colorspace。源文件中定义的所有图像都将使用 sharp 进行转换。

{
  "images": {
    "colorspace": "b-w"
  }
}

样式表

你可以使用 CSS 或 SCSS 为所有构建添加样式。stylesheets 配置允许你指定要包含在构建中的 .css 或 .scss 文件数组。以下示例展示了一个配置文件，指定在所有构建中包含两个样式表。

{
  "stylesheets": {
    "files": ["css/first.css", "css/second.scss"]
  }
}

你可以使用 {{ stylesheets }} liquid 变量标签在布局中插入编译后的 CSS。这将把每个文件作为单独的 <link> 元素插入。

<html>
  <head>
    {{ stylesheets }}
  </head>
  <body>
    {{ content }}
  </body>
</html>

通过为每种格式使用不同的文件，你可以让书籍在不同格式之间看起来非常不同。要在格式之间共享样式，你可以使用 SCSS @import。

目标位置

也可以控制这些样式表在构建中的存储位置。你可以使用 destination 属性指定自定义目标文件夹。默认值为 assets。

{
  "stylesheets": {
    "destination": "customfolder"
  }
}

压缩

compress 属性将从 CSS 文件中删除空白，从而大大减小文件大小。

{
  "stylesheets": {
    "compress": true
  }
}

打包

bundle 选项会将 stylesheets 数组中的所有文件合并为输出中的单个 CSS 文件。建议将此选项与 compress 选项结合使用，以提高生产网站的加载速度。你可以将其设置为 true 或所需的打包文件名。

{
  "stylesheets": {
    "bundle": "mybundle.css"
  }
}

摘要

digest 选项会在文件名中添加文件内容的 md5 校验和，以便你可以为生产网站设置长时间的缓存头。

{
  "stylesheets": {
    "digest": true
  }
}

JavaScript

javascripts 配置允许你指定要包含在构建中的 .js 文件数组。以下示例展示了一个配置文件，指定在所有构建中包含两个 JavaScript 文件。

{
  "javascripts": {
    "files": ["css/first.js", "css/second.js"]
  }
}

你可以使用 {{ javascripts }} liquid 变量标签在布局中插入 JavaScript 文件的链接。这将把每个文件作为单独的 <script> 元素插入。

<html>
  <head>
    {{ javascripts }}
  </head>
  <body>
    {{ content }}
  </body>
</html>

由于这是一个构建设置，你可以轻松地将 JavaScript 文件添加到某些构建中，同时保持其他构建为静态状态。

目标位置

也可以控制这些 JavaScript 文件在构建中的存储位置。你可以使用 destination 属性指定自定义目标文件夹。默认值为 assets。

{
  "javascripts": {
    "destination": "customfolder"
  }
}

压缩

compress 属性将使用 UglifyJS 从 JavaScript 文件中删除空白，从而大大减小文件大小。

{
  "javascripts": {
    "compress": true
  }
}

打包

bundle 选项会将 javascripts 数组中的所有文件合并为输出中的单个 JS 文件。建议将此选项与 compress 选项结合使用，以提高生产网站的加载速度。你可以将其设置为 true 或所需的打包文件名。

{
  "javascripts": {
    "bundle": "mybundle.js"
  }
}

摘要

digest 选项会在文件名中添加文件内容的 md5 校验和，以便你可以为生产网站设置长时间的缓存头。

{
  "javascripts": {
    "digest": true
  }
}

字体

当你想使用网络字体时，只需在你的书籍仓库中创建一个名为 fonts 的文件夹，将你的字体保存到这个文件夹中，然后在你的 CSS 中使用 font-path() scss 辅助函数引用字体文件。

@font-face {
  font-family: "MyFont";
  src: font-path("MyFont.eot");
  src: font-path("MyFont.eot?#iefix") format("embedded-opentype"), font-path(
        "MyFont.woff"
      ) format("woff"), font-path("MyFont.ttf") format("truetype"), font-path(
        "MyFont.svg#robotobold"
      ) format("svg");
  font-weight: normal;
  font-style: normal;
}

源文件

你可以通过提供一个 glob 数组来更改 magicbook 查找字体的位置，就像通用的 files 数组一样。默认模式是 fonts/**/*.*。

{
  "fonts": {
    "files": "custom/fonts/folder/**/*.ttf"
  }
}

目标文件夹

默认情况下，字体将位于每个构建的 assets 文件夹中。你可以使用 destination 属性更改此目标位置。font-path() SCSS 辅助函数将自动更新字体的相对 URL。

{
  "fonts": {
    "destination": "custom/assets/folder"
  }
}

自动生成的目录标记通常有很大的限制，所以 magicbook 不是试图猜测你想要的标记类型，而是允许你使用液体包含来生成自己的目录 HTML。 magicbook会自动解析您构建中的所有HTMLBook部分，并让您能够根据自己的喜好渲染自定义目录。首先，您需要在想要显示目录的位置添加一个liquid变量。这可以在布局文件或内容文件中。

{{ toc }}

由于liquid模板在markdown转换之前就被评估，而目录结构是在markdown转换之后生成的，magicbook会在liquid处理过程中首先插入一个占位符字符串，然后在构建过程的后期用名为toc.html的特殊包含文件的输出替换这个占位符。要生成目录，您必须在包含文件夹中有这个包含文件。该包含文件将可以访问以下对象树：

{
  id: "#section-id",
  type: "HTMLBook部分类型",
  label: "部分标题",
  children: [] // 子部分数组
}

所有使用magicbook new创建的项目都会有一个toc.html包含文件，这是一个很好的参考，可以看到有哪些可能性。

布局

像大多数Web框架一样，magicbook可以将您的内容包装在布局文件中。这里使用liquid模板语言，布局文件可能如下所示：

<html>
  <head>
    <title>我的书</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

要指定要使用的布局，您可以在JSON配置中使用layout属性。

{
  "layout": "layouts/main.html"
}

布局支持使用liquid包含（即使liquid插件被禁用）。更多信息请参见liquid插件部分。您也可以通过YAML前置元数据控制每个文件的布局，如下所述。

Liquid

您也可以在源文件中使用Liquid模板。默认情况下，每个文件都可以访问以下变量：

format是一个字符串，包含构建格式的名称。
config是一个对象，包含特定格式的所有配置设置。
page是一个对象，包含特定文件的YAML前置元数据变量。

使用这些变量，您可以创建在不同格式中有不同标记的书籍。这里有一个简单的文件示例。

{% if format == 'pdf' %}
这是PDF版本的文本
{% else %}
这是其他所有格式的文本
{% endif %}

包含文件

您可以使用Liquid包含文件来重用相同的标记，而无需复制粘贴。默认情况下，magicbook会在includes文件夹中搜索包含文件，因此无需任何配置设置，您可以在includes/myview.html中创建一个如下所示的文件：

<p>这是我的包含文件</p>

...然后在任何文件中像这样使用包含文件：

{% include myview %}

如果您想向包含文件传递变量，可以在include命令中添加属性列表，这些变量将在包含文件中以include.VARIABLENAME的形式可用。

{% include myview onevar="这是一个变量" anothervar="这是另一个变量" %}

您可以通过includes配置设置更改magicbook查找包含文件的位置。

{
  "liquid": {
    "includes": "my/include/folder"
  }
}

这使得可以为每种格式使用不同的包含文件，或者为所有格式使用单一的包含文件，其中使用format liquid变量来生成特定的模板标记。

YAML前置元数据

您可以在每个文件中指定YAML前置元数据，并使这些变量在文件内容中作为liquid变量可用。以下是一个简单的示例，说明这是如何工作的。

---
name: Rune Madsen
---

# 关于作者

作者{{ name }}出生于丹麦。

YAML前置元数据还允许您为每个文件覆盖一些配置。例如，您可以为文件指定自定义布局。这将覆盖配置文件中的任何设置。如果您希望为单个文件禁用布局，可以将布局设置为none。

---
layout: layouts/introduction.html
---

这仅适用于以下配置变量：

layout
includes

插件

magicbook中的所有功能都是通过插件编写的。这既使得可以禁用几乎任何你不想要的功能，也可以轻松地在自定义插件中添加新功能。

添加插件

编写自定义插件很容易。您可以在书籍仓库中放置一个文件，并在插件数组中引用它。以下将尝试加载位于书籍文件夹中plugins/myplugin.js的文件。

{
  "addPlugins": ["plugins/myplugin"]
}

您也可以创建NPM包形式的插件，只需使用包的名称即可。

{
  "addPlugins": ["mypackage"]
}

每个插件可以通过add()、before()和after()函数在插件注册表中注册来钩入构建流程。请查看src/plugins/blank.js文件以了解基本插件，或浏览原生插件以了解它们是如何实现的。要打印所有插件函数的顺序，请运行magicbook build --verbose。

如果您创建了自定义插件，请添加magicbook-plugin关键字，以便它出现在插件列表中。