Skip to content
Map HTML files for use with next-book tools
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Next-book publishing tool: nb-mapper

Nb-mapper is a tool for mapping HTML files for use with next-book tools. See an example, API documentations or a example book created with nb-mapper, that builds functionalityon top of its markup: displaying and remembering position, tracing reader's journey through a book etc.

Use with node.js

Install in a book's repository (global installation is discouraged as nb-mapper is in its early development and API changes are expected):

npm i nb-mapper

CLI use

Use nb-mapper command, e. g.

nb-mapper --src text --out book

Mapper reads all \*.html files in the source directory (--src, by default ./src), sorts them by filename, maps them and outputs the result into the output directory (--out, by default ./book).

It also creates a spine.json file that collects metadata about the book and adds several structural meta tags into files (prev, next, license, spine) that allow book traversal (with Javascript or native browser affordances).

It's required to include a book.json file in the source directory that adds metadata and a list of chapters. It's possible to specify static folders that will be copied from source to output as they are.

  "meta": {
    "title": "Free Culture",
    "author": "Lawrence Lessig",
    "subtitle": "How big media uses technology and the law to lock down culture and control creativity",
    "published": 2004,
    "keywords": ["copyright law", "intellectual property", "public domain", "web", "Napster"]
  "chapters": [
  "static": ["style", "scripts", "images"]

You can preview the book on a local web server by running the nb-mapper with -w flag (or with --server param).

nb-mapper --src text --out book --server

Use in browser

Download nb-mapper from npm or github and include it in your project files. Check the example with extensive highlighting to see how the result looks like.

<script type="text/javascript" src="nb-mapper/dist/browser.js"></script>
<script type="text/javascript">
  window.addEventListener('load', () => NbMapper.mapHtml());

Browser use is currently primarily for quick try-outs, not intended for production use.

Use in a Node.js script

Map HTML string or JSDOM objects in a script:

const html = '...';
const mapper = require('nb-mapper');;

Config the mapper with an options object, conf), see API docs for Options.


Clone repository and install devDependencies. Build a complete project with npm run build. Limit PRs only to changed source files.

You can’t perform that action at this time.