document-it
v1.0.3
Published
A Node.js pandoc-wrapping library for declarative document generation.
Downloads
2
Readme
Document It
A Node.js pandoc-wrapping library for declarative document generation.
This project is an example of "bodging". It will contain bugs, and it will fail inexplicably at times.
Installation
npm install document-it
Usage
At the root of your project, make a directory called filters
and add some JS
or CJS files like the following:
// your filter MUST be a class extending this one
const { Filter } = require("document-it");
class MyFilter extends Filter {
activation = "always"; // either `"always"` to run for every document, or
// `{ yamlFilter: "filter-name" }` to run only if a
// document's metadata contains a key `filter` with
// an array entry of `"filter-name"`
// whatever you return from here will be inserted into the document, replacing
// the given element
async filter(element) {
this.format; // populated with the format of the current document
this.meta; // populated with the metadata of the current document (AST format)
this.frontmatter; // populated with the document-it frontmatter of the current document (JSON format)
// creates an element with the given type, attributes, and content
return this.createElement(
"Header", // element type
1, // header level
["id", ["class-1", "class-2"], [["attr-name", "attr-value"]]], // attributes
[this.createElement("Str", "Hello World")], // content
);
}
};
// your filter class MUST be the default export
module.exports = MyFilter;
Once you have these set up, create a documents
folder in your project's root
and add some .md
files.
---
title: foo
subtitle: bar
tocdepth: 3
outputExt:
- pdf
- docx
filters:
- my-custom-filter
---
## Foo bar
Lorem ipsum dolor sit.
Then, run the following:
npx document-it
This will generate an output
folder in your project root with a .pdf
and
.docx
version of your markdown files.
Configuration
Configuring Document It
You can use any of the given names for a config file. The config file must contain valid JSON, and not include comments.
The names, in order of precedence, are:
.documentitrc
.documentitrc.json
.docitrc
.docit.json
The config file can contain any, all, or none of the following information:
interface Config {
/**
* Where user-created filters are stored
*
* @default "filters"
*/
filterDir: string;
/**
* Where your source documents are stored.
*
* Throws an error if this is the same as `outputDir`.
*
* @default "documents"
*/
sourceDir: string;
/**
* The extension of your source documents.
*
* @default ["md"]
*/
sourceExt: string[];
/**
* Where your output documents are stored.
*
* Throws an error if this is the same as `sourceDir`.
*
* @default "output"
*/
outputDir: string;
}
Configuration can also be done via the command line:
document-it --filterDir=filters --sourceDir=documents --sourceExt=md --outputDir=output
Configuring Documents
Documents can provide options to document-it via their frontmatter. The frontmatter must be valid YAML.
The options that document-it recognizes are below, other options may be passed, for example pandoc metadata.
interface DocumentFrontMatter {
/**
* The extension of your output documents.
*
* @default ["pdf", "docx"]
*/
outputExt: string[];
/**
* The filters to use.
*/
filters?: string[];
/**
* Sets the Table Of Contents (toc) depth.
* Also implies generating a toc.
*
* Setting to `0` will disable the toc.
* @default 2
*/
tocDepth?: number;
/**
* Produces a standalone document.
*
* @default true
*/
standalone?: boolean;
}
An example frontmatter using all the defaults would look like:
outputExt:
- pdf
- docx
# no optional filters are enabled by default
# filters:
# - my-custom-filter
tocDepth: 2
standalone: true
Examples
For an example project using this library, see the examples folder.
If you want to download the example folder on it's own, you can use Download Directory, or click here: THIS LINK AUTOMATICALLY BEGINS THE DOWNLOAD
License
Document It is licensed under the MIT License