BookMarkDown

Welcome to BookMarkDown. This document will give you an overview of BookMarkDown, how it works, how to configure it, and how to publish your own books.

What is BookMarkDown?

BookMarkDown is a self-publishing system using JSON and MarkDown. It enables people with a moderate amount of experience with MarkDown and JSON to publish a book with very little work. BookMarkDown includes themes for HTML and PDF output, as well as the ability to customize the look and feel of the output.

BookMarkDown is ever-evolving, but aims to be backward-compatible as it grows.

Installing

Installation is straight-forward as long as you have Node.js installed. BookMarkDown can be installed using the Node Package Manager:

$ npm install -g bookmarkdown

Doing this installs two tools, initbmd which creates you a new skeleton copy of a book, and bmd2html which converts a book into HTML format for display on the web. More formats are in the works, including native support for PDF and MOBI. These will be added as addition commands.

Creating a Book

Creating the skeleton of a book is easy. This can be done by running a single command.

$ initbmd mybook

This will create a directory called mybook containing a starter book.json file as well as an empty chapter.

A BookMarkDown book is separated into two parts, the book.json file, and subsequent chapters. These are matched with a theme, which includes styling choices and rendered into a final book.

The Skeleton

The skeleton of a BookMarkDown book is the book.json file. The book.json file describes the meta aspects of the book, including the title, author, and the makeup of the book itself.

This is an example of a BookMarkDown book.json file:

{
  "title": "BookMarkDown",
  "subtitle": "Documentation",
  "author": {
      "firstname": "Jerry",
      "lastname": "Sievert"
  },
  "preface": "chapters/preface.bmd",
  "chapters": [
    "chapters/chapter1.bmd"
  ]
}

This defines the title, subtitle, author, preface, and chapters of the book. Each instance of a chapter and a preface is built of a .bmd file, a hybrid of JSON and MarkDown.

.bmd Files

.bmd files are broken down into two parts: JSON and MarkDown separated by a delimiter, %%%. The JSON defines the parameters of the chapter, and the MarkDown defines the text of the chapter itself.

%%%
{
  "title": "Chapter 1 - A Vision"
}
%%%
This is the story of a man and his horse.

## The Horse

Let's begin the story talking about the horse.  He was a good horse, sturdy.

The JSON defines the meta-data about the chapter itself, in this case, the title: Chapter 1 - A Vision. This title is used to both construct the table of contents, as well as populate the title of each chapter or preface.

Rendering a book is straightforward. Currently, only rendering to HTML is supported, but once it is rendered to HTML, it can be saved as a PDF in a browser.

EPUB rendering is coming soon, but is not currently there, nor is MOBI.

$ bmd2html --book book.json

This will render the book described in book.json into a directory called out.

There are additional options for rendering available.

$ bmd2html
Convert BookMarkDown to HTML
Usage bmd2html

Options:
  --theme   theme to use                 [default: "default"]
  --out     output directory             [default: "./out"]
  --config  optional configuration file
  --book    bookmarkdown file            [required]

BookMarkDown can be configured with an optional JSON configuration file. This file can be used to give tighter control of some aspects of the rendering system.

Themes

Themes allow for altering the look and feel of the rendering of BookMarkDown. A theme can be configured as either a String or a Directory. If the theme is a String, it will be used to select which theme, by name, to use.

{
  "theme": "default"
}

The default theme is titled "default", and refers to the theme in the themes/html directory of the BookMarkDown project.

If a theme is configured as an Object, it contains specific aspects to the theme.

{
  "theme": {
    "directory": "./myCustomTheme"
  }
}

If a "themes" Object is present, it defines all properties of named themes. This is used internally for mapping of theme names to theme properties, but can be overridden in the configuration file.

{
  "themes": {
    "default": "./themes/html/default"
  }
}