Documark

PDF generator for scripted documents.

A library that:

1. Converts a scripted document (HTML, CSS, and JavaScript) to a PDF (using wkhtmltopdf)

2. Is used as a command line interface:

   $ npm install -g documark-cli
   $ cd /path/to/my-document/
   $ npm install documark
   $ edit document.html
   $ documark compile

3. Can watch for files changes to recompile the document (documark compile --watch)

Why?

My personally hatret towards WYSIWYG word processors (Word, Pages, etc.) sparked me to write this tool. I have used LaTeX for a while, but it felt like a waste of time. So instead I figured: why not use web technologies? I like Documark because it:

1. Separates content and styling
2. Uses mature webtechnologies like HTML, JS, and CSS for writing and styling the document
3. Enforces a consistent document style. No more dragging around of table columns and floating images
4. Allows version control with Git or SVN
5. Simplifies collaboration by version control and splitting up the document into separate files
6. Allows you to use your favorite text editor - like Vim ❤
7. Makes automating things (through plugins) real easy
8. Enables you to use libraries like D3 and MathJax for generating graphs and math formulas!

Getting started

Install

1. Run npm install -g documark-cli to make the documark command available
2. Currently manually installing wkhtmltopdf v0.12.2.1+ is still required, but we're working on this!

Example

Go to the Documark example repository for a generated PDF and its source code.

From scratch

1. Install the Documark CLI and wkhtmltopdf

2. Navigate to (an empty) document directory: $ mkdir ~/Documents/MyDocument && cd $_

3. Install Documark: $ npm install documark

4. Install some basic styling: $ npm i dmp-style-basic

5. Add a document.html file:

   <!--
   title: My Document
   plugins:
   	- dmp-style-basic
   -->
   
   <chapter>
   	<h1>My Document</h1>
   	<p>Hello world!</p>
   </chapter>

6. Run $ documark compile

7. And finally open Document.pdf

Usage

Configuration

Document configuration can be done in two ways:

1. In the document's front matter.
2. In a separate config.json file.

If there is front matter in the document, the configuration file will be ignored.

Plugins

Add plugins via the plugins key in the document.html front matter:

<!--
{
	"title": "Document",
	"plugins": ["dmp-plugin-loader", "dmp-hr-to-page-break"]
}
-->

Plugins all have the documark-plugin keyword. They are listed on the NPM website.

Tip: Use the documark plugin loader to load custom plugins!

Themes

Themes are loaded as plugins and should be prefixed with dmp-theme-. A theme generally consists of some styling and other useful plugins, like table of contents, page headers, footers, margins, or math equations.

Styling

The easiest way is to load a predefined document style as a plugin. These plugins are prefixed with dmp-style-.

Another way of styling your document is through CSS files, inline CSS, or the element's style attribute.

Build process

These are the steps for compiling the PDF document:

1. Input files (HTML, configuration, and assets)
2. Convert to DOM tree (with CheerioJS)
3. Process plugins (which can alter the DOM and PDF configuration)
4. Emit pre-compile event
5. Generate PDF
6. Emit post-compile event

wkhtmltopdf

Configure wkhtmltopdf with the pdf object in the documents front matter. For example:

<!--
{
	"title": "Document",
	"pdf": {
		"userStyleSheet": "path/to/main.css"
	}
}
-->

Note that node-wkhtmltopdf is used as an intermediate package, which uses camel cased (userStyleSheet) options instead of dashed ones (user-style-sheet, like in the command line tool). See this page for a full list of configuration options.

Plugin development

Writing your own plugins is easy! Here's a boilerplate for a plugin named dmp-my-custom-plugin (dmp- is short for Documark plugin):

// Require modules outside the plugin function
var path = require('path');

// Add camel cased plugin name to function (for debugging)
module.exports = function dmpMyCustomPlugin ($, document, done) {
	// Manipulate the DOM tree
	$('my-custom-element').replaceWith('<p>Hello world!</p>');

	// Or alter the configuration
	document.config().pdf.marginLeft = '5cm';

	// Don't forget to let Documark know the plugin is done!
	done();
};

A plugin has the following parameters:

• $: the CheerioJS DOM tree (works a lot like jQuery) of the entire document.
• document: the Document instance. Use document.config() to get/set configuration variables.
• done: the callback function. Don't forget to call this at the end!

Finally load your plugin in your document configuration:

<!--
{
	"plugins": ["dmp-my-custom-plugin"]
}
-->

<chapter>
	<my-custom-element />
</chapter>

Roadmap

1. Move CLI commands to documark-cli
2. Refactor codebase
3. Add unit tests (for Travis)
4. Research alternatives to wkhtmltopdf (#12)
5. Use wkhtmltopdf binary package to automatically download the required wkhtmltopdf tools
6. Build tools for debugging (dmp-debug, logger etc)
7. Improve support: set up website, write wiki pages, and set up IRC channel
8. Create Yeoman generator for easy document/plugin setup: yo documark and yo documark-plugin
9. Including code files/snippets with highlighting
10. Create scientific - LaTex like - theme
11. Landscape pages (not possible yet ◔̯◔)