Documark
PDF generator for scripted documents.
A library that:
- Compiles scripted document files (Jade, Markdown, and assets) into a PDF.
- Is used as a command line interface (
npm install -g documark-cli
). - 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:
- Separates content and styling.
- Uses mature webtechnologies like Markdown, HTML, JS, and CSS for writing and styling the document.
- Enforces a consistent document style. No more dragging around of table columns and floating images.
- Allows version control with Git or SVN.
- Simplifies collaboration by version control and splitting up the document into separate files.
- Allows you to use your favorite text editor - like Vim ❤ .
- Makes automating things (through plugins) real easy.
- 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
- Currently manually installing wkhtmltopodf v0.12.2.1+ is still required.
Build process
These are the steps for compiling the PDF document:
- Input files (Jade, Markdown, and assets)
- Generate HTML
- Convert to DOM tree (with CheerioJS)
- Process plugins (which can alter the DOM and PDF configuration)
- Emit
pre-compile
event - Generate PDF
- Emit
post-compile
event
Configuration
Document configuration can be done in two ways:
- In the document's front matter.
- 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: Documentplugins: - dmp-plugin-loader - dmp-hr-to-page-break---
Alternatively use JSON front matter:
---json---
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: Documentpdf: 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 functionvar path = ; // Add camel cased plugin name to function (for debugging)module { // Manipulate the DOM tree ; // Or alter the configuration documentpdfmarginLeft = '5cm'; // Don't forget to let Documark know the plugin is done! ;};
A plugin has the following parameters:
$
: the CheerioJS DOM tree (works a lot like jQuery) of the entire document.document
: the Document instance. Usedocument.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
- Move documark CLI commands to this repository.
- Rename
documark-
prefixed plugins and themes todmp-
anddmp-theme-
respectively. - Research alternatives to wkhtmltopdf (#12).
- Use wkhtmltopdf binary package to automatically download the required wkhtmltopdf tools.
- Build tools for debugging (dmp-debug, logger etc).
- Improve support: set up website, write wiki pages, and set up IRC channel.
- Create Yeoman generator for easy document/plugin setup:
yo documark
andyo documark-plugin
. - Including code files/snippets with highlighting.
- Create scientific - LaTex like - theme.
- Landscape pages (not possible yet ◔̯◔).