magicbook

Add YAML frontmatter to the top of your Markdown files to define variables or override configuration.

Defining Variables: Variables defined in frontmatter are available as Liquid variables.

---
name: Rune Madsen
---
# About the author

The author, {{ name }}, was born in Denmark.

Overriding Configuration: You can override the following configuration keys per file:

• layout (set to none to disable)
• includes

Liquid is enabled by default in source files. Each file has access to three primary variables:

• format: The name of the current build format (e.g., pdf, html).
• config: The configuration object for the specific format.
• page: An object containing the YAML frontmatter variables from the current file.

Example: Format-specific content

{% if format == 'pdf' %}
Here's some text for the PDF
{% else %}
Here's some text for all the other formats
{% endif %}

You can organize your book into logical groups using an object syntax within the files array. These parts are automatically added to the Table of Contents. If using the permalink setting, the labels can be used in slugs via the :parts variable.

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

All functionality in magicbook is implemented via a plugin system. This architecture allows you to disable specific features or extend the build pipeline with custom logic. Plugins can hook into the build pipeline by registering via add(), before(), and after() functions.

To inspect the current plugin execution order and identify available plugin names, run the build command with the --verbose flag.

magicbook build --verbose

Instead of auto-generated markup, magicbook allows you to build a custom TOC using a liquid include.

1. Place {{ toc }} in your layout or content file where you want the TOC to appear.
2. Create a toc.html file in your includes folder.
3. The toc.html include has access to a hierarchical object representing your book structure:

{
  id: "#id-of-the-section",
  type: "Type of HTMLBook section",
  label: "Title for section",
  children: [] // array of child sections
}

<!-- In your layout or content file -->
{{ toc }}

<!-- In includes/toc.html (example logic) -->
<ul>
  {% for item in toc %}
    <li>{{ item.label }}</li>
  {% endfor %}
</ul>

Magic Book supports .md and .html source files. It uses a layer called HTMLBook which relies on data-type attributes to define the book structure (chapters, sections, etc.).

• Markdown: Automatically converted to HTMLBook. Headers (#, ##, etc.) are mapped to nested <section> elements with data-type attributes (e.g., chapter, sect1, sect2).
• HTML: You must manually use HTMLBook data-type attributes if you want features like automatic Table of Contents generation to work.

<!-- Example of HTMLBook markup generated from Markdown -->
<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>

Project configuration is managed through a magicbook.json file located in your project root. The magicbook build command automatically detects this file. If your configuration file is in a non-standard location or has a different name, use the --config flag.

magicbook build --config=myfolder/myconfig.json

Magic Book automatically resolves cross-references between files.

• Markdown: Use standard Markdown links to an ID: [Go to target](#mytarget). Ensure the target has an <a id="mytarget"></a> in the destination.
• HTML: Use the HTMLBook xref data-type: <a href="#mytarget" data-type="xref">Go to target</a>.

[Go to my target](#mytarget)

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

To use magicbook, install it globally via npm, generate a new project template, and then run the build command. By default, a new project creates a build directory containing both a website (HTML) and a PDF version of your book.

# Install the package globally
npm install magicbook -g

# Generate a new project
magicbook new myproject

# Build the book
cd myproject
magicbook build

Magic Book supports standard Markdown image syntax to include images in your book. You can reference images using relative paths (local files) or absolute URLs (external images).

Local Images

To include a local image, provide the path relative to the current file location:

• Same directory: ![alt text](image.jpg)
• Subdirectory: ![alt text](subfolder/image.png)
• Parent/Random paths: ![alt text](../path/to/image.jpg)

External Images

To include an image hosted online, use the full URL:

• ![alt text](http://example.com/image.jpg)

![A picture of bruce springsteen](bruce.jpg)

![Another picture of bruce springsteen](subfolder/bruce.png)

![An external image](http://www.runemadsen.com/image.jpg)

To include images, use the standard Markdown image syntax. The build system looks for the image file relative to the expected image directory (e.g., images/).

![Alt text](image-name.jpg)

You can create links to other chapters or sections within your project using standard Markdown internal link syntax. The Magic Book build process automatically resolves these links by searching for the target ID across all files and appending the necessary filename for the output format.

[link text](#target-id)