Documark

PDF generator for scripted documents.

A library that:

1. Compiles scripted document files (Jade, Markdown, and assets) into a PDF.
2. Is used as a command line interface (npm install -g documark-cli).
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 Markdown? I like Documark because it:

1. Separates content and styling.
2. Uses mature webtechnologies like Markdown, 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!

Example

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

Dependencies

1. Currently manually installing wkhtmltopodf v0.12.2.1+ is still required.

Build process

These are the steps for compiling the PDF document:

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

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.jade front matter:

---
title: Document
plugins:
  - dmp-plugin-loader
  - dmp-hr-to-page-break
---

Alternatively use JSON front matter:

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

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

Themes

Themes are loaded as plugins and should be prefixed with dmp-theme-.

Note: Currently the default theme (dmp-theme-default) is not consistent with this, which I will fix soon (see Roadmap).

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

Available plugins

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

Roadmap

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