The Magic Book Project

This project is still working towards a 1.0.0 release, which means that the API is in active development. EPUB and MOBI formats are still not supported. We encourage developers to try the releases and report any issues in the issue tracker.

The Magic Book Project is an open source project funded by New York University's Interactive Telecommunications Program. It aims to be the best free tool for creating print and digital books from a single source.

This project is for you, if:

[x] You want to write your book in plain text (Markdown or HTML)
[x] You want to export to a static website
[x] You want to export to a printable PDF
[ ] You want to export to EPUB (Apple Books, etc)
[ ] You want to export to MOBI (Kindle)
[x] You want your source to be free of format-specific hacks
[x] You want to use CSS to design the look of your book
[x] You want to use JavaScript to add interactivity to digital formats
[x] You want to use a command-line tool for all of this
[x] You want that command-line tool be be written in Node-only. No more XSLT.

Although a small number of open source publishing frameworks already exists, it's hard to find any that are flexible enough to create modern, interactive books for the web while also doing print-ready PDF export.

Much of the functionality of magicbook exists in the form of plugins, so if you can't find specific functionality in the core, perhaps it exists in the plugin list.

Getting Started

First install the magicbook package:

npm install magicbook -g

Then run the new project generator:

magicbook new myproject

This will give you a very basic project folder with a magicbook.json configuration file. Now cd into the new project and build the book.

cd myproject
magicbook build

You now have a myproject/build directory with two builds: a website and a PDF. This is of course a very basic setup. Consult the rest of this README for all the available functionality.

Configuration

To specify configuration for your project, magicbook uses a file called magicbook.json in your project folder. When you run magicbook build, the configuration file will automatically be detected. If you wish to have a custom name and location for the configuration file, you can use the --config command line argument.

magicbook build --config=myfolder/myconfig.json

Source files

You can write your book in .md, .html, or both. magicbook uses a very simple layer on top of HTML5 called HTMLBook to define the various elements in a book. This mostly means using a few data-type attributes to specify chapters and sections, and it's very easy to learn. It is also what makes it possible magicbook to do its magic when generating table of contents, etc.

Writing in Markdown

If you chose to write your book in Markdown, magicbook will automatically convert your markdown to HTMLBook. A simple file like the following...

# Chapter title

## Sect 1

### Sect 2

... will be converted to the following HTMLBook markup.

<section data-type="chapter">
  <h1>Chapter Title</h1>
  <section data-type="sect1">
    <h1>Sect 1</h1>
    <section data-type="sect2"><h2>Sect 2</h2></section>
  </section>
</section>

Writing in HTML

If you choose to write in HTML, you will need to make sure that you're using the HTMLBook data-type attributes. magicbook will not break if you don't use them, but it won't be possible to generate a table of contents, etc.

The files array

You can specify the files to build by adding a files array to your magicbook.json file. If you do not have a files array, it will look for all markdown files in content/*.md.

You can set the files property to be a single glob.

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

You can set the files property to be an array of globs.

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

Using an array, you can also specify each of the files you want to build.

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

If you are not using the permalink setting, your glob structure will determine the output path in the build folder. If your glob uses wildcards *, the folders will be preserved in the build folder.

If you are using this approach, you can use numbers in folders and filenames to order your files, as the build process will remove leading numbers, dashes and underscores from folders and filenames. Take the following files:

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

... and this configuration file:

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

... will by default create a html build that looks like this:

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

If you want to have more control over folders and filenames, use the permalink setting.

Parts

You can use a special object syntax to group your files into parts and sub-parts. The following example demonstrates a book with an introduction and two parts with several chapters in each. These parts will automatically be added to the table of contents, and the labels will be used in the slug when using the permalinks setting with the :parts variable.

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

You can also have sub-parts, which is demonstrated in the following:

{
  "files": [
    {
      "label": "Part",
      "files": [
        "first-chapter.md",
        {
          "label": "Sub Part",
          "files": ["second-chapter.md"]
        }
      ]
    }
  ]
}

If you add extra properties to a part, it will be accessible as a liquid variable in the files. The following demonstrates a very simple use case, where "Hello" is inserted into a file.

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

This is my file. {{ part.myVariable }}

Builds

You must add a builds array to your configuration that as a minimum defines the format of each build. Here's a simple example with the bare minimum configuration to build your book into a website.

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

The builds array is a very powerful concept, as it allows you to specify settings for each build. For example, here's a book that uses a different introduction for the HTML and PDF builds. All settings in magicbook can be specified as either a global setting or a build setting.

{
  "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"
      ]
    }
  ]
}

Using the builds array, you can have several builds that uses the same format. This is useful if you want to e.g. generate a PDF with hyperlinks, and another PDF for print that doesn't have hyperlinks.

Build destination

destination specifies where to put the builds. Because you can have many builds, the default destination is build/:build, which will create a build folder within build for each build (build/build1, build/build2, etc).

You can change this setting in your configuration file.

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

Build Format

magicbook has the following built-in formats.

HTML

The html format will save all source files as separate .html files as a static website.

PDF

The pdf format will combine all source files, bundle them into a single .html file, and generate a PDF in the format destination folder. Currently this process uses Prince XML for PDF generation, as it's one of the few applications that can do print-ready PDF files from HTML. You will need a Prince XML license to use it without a watermark.

You can define settings for Prince XML.

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

EPUB (TODO)

MOBI (TODO)

Permalinks

You can use the permalink setting to override the default glob-controlled build paths. Any occurrence of the string :title will be replaced with the original filename, so the following configuration can be used to make "pretty" permalinks.

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

Any occurrence of the string :parts will be replaced by the parts that the file belongs to, so if a file belongs to a sub-part, :parts/:title.html will result in a build file located in part/sub-part/filename.html.

Links

magicbook can automatically resolve cross references. If you're writing in Markdown, simply create an ID in your destination document:

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

... and then link to that ID from any file:

[Go to my target](#mytarget)

The same is true if you're writing in HTML, but you need your link to have a the xref HTMLBook data-type:

<a href="#mytarget" data-type="xref">Go to my target</a>

magicbook will automatically figure out whether or not to insert the destination file into the href, depending on the build settings.

If you want to insert page numbers in link text for print, it's easy with Prince XML and CSS.

Auto-generated ID's

By default, magicbook will add an auto-generated ID on every section with a HTMLBook data-type at

Magicbook

Install / Use

README