Update documentation for v0.2.0

Author: mcecode

README.md

@@ -20,9 +20,7 @@ Thus, PME was born.
 
 To fulfill the requirements that I was looking for, the PME CLI takes data from a [YAML](https://yaml.org), [JSON](https://www.json.org/json-en.html), JSON with Comments (JSONC), or [JSON5](https://json5.org) file and injects it into a template to generate HTML which is then used to generate a PDF using [Puppeteer](https://pptr.dev). This process is repeated whenever there are changes to either the data or template file so that the PDF preview can refresh automatically.
 
-Presently, the default template engine used to generate HTML is [Liquid](https://liquidjs.com). This can be changed when using PME as a library, but not as a CLI. However, in the future, [it is planned](#todos) to make this configurable in the CLI as well via [the config file](docs/01-cli.md#configuration).
-
-Additionally, the autorefresh feature currently only works if the viewer used to preview the PDF supports repainting when there are changes to the PDF file. Though, it is also in [the plan](#todos) to add an auto-reloading viewer together with the CLI to make previewing changes more streamlined.
+Currently, the autorefresh feature only works if the viewer used to preview the PDF supports repainting when there are changes to the PDF file. However, in the future, [it is planned](#todos) to add an auto-reloading viewer together with the CLI to make previewing changes more streamlined.
 
 ## Requirements
 

docs/01-cli.md

@@ -28,25 +28,75 @@ Examples:
 
 ## Configuration
 
-The CLI can be configured using an [ECMAScript module](https://nodejs.org/api/esm.html) config file with a `.mjs` extension. By default, it will search for a file named `pme.config.mjs` in the current working directory. If not found, it will continue searching for this file up the directory tree. If there is no `pme.config.mjs` file found in the directory tree, it will try to look for it in the home directory. Alternatively, you can pass the path to a config file using the `--config` or `-c` option.
+The CLI can optionally be configured using an [ECMAScript module](https://nodejs.org/api/esm.html) config file with a `.mjs` extension. By default, it will search for a file named `pme.config.mjs` in the current working directory. If not found, it will continue searching for this file up the directory tree. If there is no `pme.config.mjs` file found in the directory tree, it will try to look for it in the home directory. Alternatively, you can pass the path to a config file using the `--config` or `-c` option.
 
-If present, the config file is expected to have a default object export with the following optional properties:
+### Options
 
-- [`templateOptions`](https://liquidjs.com/api/interfaces/liquid_options_.liquidoptions.html), this will be passed to the template renderer, which is [Liquid](https://liquidjs.com).
-- [`pdfOptions`](https://pptr.dev/api/puppeteer.pdfoptions), this will be passed to the PDF renderer, which is [Puppeteer](https://pptr.dev).
+If present, the config file is expected to have a default object export with the following optional properties and methods:
 
-Below is an example of a config file:
+#### `templateOptions`
+
+- Type: `object | undefined`
+- Description: Options passed to the template renderer
+- [Default template renderer options reference](https://liquidjs.com/api/interfaces/liquid_options_.liquidoptions.html)
+
+#### `pdfOptions`
+
+- Type: `object | undefined`
+- Description: Options passed to the PDF renderer
+- [PDF renderer options reference](https://pptr.dev/api/puppeteer.pdfoptions)
+
+#### `getTemplateRenderer`
+
+- Type: `function | undefined`
+- Description: Returns a custom template renderer using the options passed from `templateOptions`
+- Signature: `(options?) => (template: string, data?: object) => string | Promise<string>`
+
+### Examples
+
+**Tip:** If PDF Made Easy is installed locally or a global install is [`npm link`ed](https://docs.npmjs.com/cli/v9/commands/npm-link), you can add a [JSDoc](https://jsdoc.app) `@type` comment for [IntelliSense](https://en.wikipedia.org/wiki/Intelligent_code_completion) like in the examples below.
+
+#### Passing options to the template and PDF renderers
 
 ```js
 /** @type {import("pdf-made-easy").PMEConfig} */
 export default {
   templateOptions: {
-    // ...
+    jsTruthy: true,
+    globals: {
+      custom: "global variables here"
+    }
   },
   pdfOptions: {
-    // ...
+    format: "LEGAL",
+    landscape: true,
+    margin: {
+      top: "0.5in",
+      bottom: "0.5in",
+      left: "1in",
+      right: "1in"
+    }
   }
 };
 ```
 
-The [JSDoc](https://jsdoc.app) `@type` comment helps to provide [code completion](https://en.wikipedia.org/wiki/Intelligent_code_completion) when using editors that support loading [declaration files](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html).
+#### Using a custom template renderer
+
+```js
+import Handlebars from "handlebars";
+
+/**
+ * @type {import("pdf-made-easy").PMEConfig<Parameters<Handlebars.compile>[1]>}
+ */
+export default {
+  // 'templateOptions' will be passed to the 'getTemplateRenderer' method below
+  // as 'options'.
+  templateOptions: {
+    noEscape: true,
+    strict: true
+  },
+  getTemplateRenderer(options) {
+    return (template, data) => Handlebars.compile(template, options)(data);
+  }
+};
+```

docs/02-api.md

@@ -2,74 +2,87 @@
 
 **Note:** PDF Made Easy is [ECMAScript modules only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c), meaning, it can only be `import`ed, not `require`d.
 
-The full documentation for PDF Made Easy's API is yet to be written. However, for now, [intellisense](https://en.wikipedia.org/wiki/Intelligent_code_completion) and the [library's declaration file](../index.d.ts) would probably give you a good enough idea of how to use it.
+The full documentation for PDF Made Easy's API is yet to be written. However, for now, [IntelliSense](https://en.wikipedia.org/wiki/Intelligent_code_completion) and the [library's declaration file](../index.d.ts) would probably give you a good enough idea of how to use it.
 
 For most use cases where a customized script is needed, the `Builder` object will likely suffice. Below is an example of how to use it:
 
 ```js
 import Handlebars from "handlebars";
-import { getBuilder, getDefaultTemplateRenderer } from "pdf-made-easy";
+import { getBuilder } from "pdf-made-easy";
 
 // Instantiates the 'Builder' object and resources needed for PDF generation.
 const builder = await getBuilder();
 
 // Generate a PDF from 'template.liquid' with data injected from 'data.yml' and
-// emit it to an 'output.pdf' file.
-// Relative file paths will be resolved in the current working directory.
-// 'getDefaultTemplateRenderer' returns the default template renderer which
-// uses Liquid.
+// emit it to an 'output.pdf' file. Relative file paths will be resolved in the
+// current working directory.
 await builder.build({
   data: "data.yml",
   template: "template.liquid",
-  output: "output.pdf",
-  getTemplateRenderer: getDefaultTemplateRenderer
+  output: "output.pdf"
 });
 
 // Use a JSON data file.
 await builder.build({
   data: "data.json",
   template: "template.liquid",
-  output: "output.pdf",
-  getTemplateRenderer: getDefaultTemplateRenderer
+  output: "output.pdf"
 });
 
 // Resolve relative file paths in a custom directory.
 await builder.build(
   {
     data: "data.yml",
     template: "template.liquid",
-    output: "output.pdf",
-    getTemplateRenderer: getDefaultTemplateRenderer
+    output: "output.pdf"
   },
   "/my/custom/root/directory/where/relative/paths/will/be/resolved/in"
 );
 
-// Use Handlebars as the templating engine.
+// Pass options to the templating engine and the PDF renderer.
 await builder.build({
   data: "data.yml",
-  template: "template.hbs",
+  template: "template.liquid",
   output: "output.pdf",
-  getTemplateRenderer(options) {
-    return (template, data) => Handlebars.compile(template, options)(data);
+  options: {
+    templateOptions: {
+      jsTruthy: true,
+      globals: {
+        custom: "global variables here"
+      }
+    },
+    pdfOptions: {
+      format: "LEGAL",
+      landscape: true,
+      margin: {
+        top: "0.5in",
+        bottom: "0.5in",
+        left: "0.5in",
+        right: "0.5in"
+      }
+    }
   }
 });
 
-// Pass options to the templating engine and the PDF renderer.
+// Use Handlebars as the templating engine.
 await builder.build({
   data: "data.yml",
-  template: "template.liquid",
+  template: "template.hbs",
   output: "output.pdf",
-  getTemplateRenderer: getDefaultTemplateRenderer,
   options: {
+    // The @type JSDoc adds proper IntelliSense. When using TypeScript, the type
+    // can be passed as a generic type to 'Builder.build'.
+    /** @type {Parameters<Handlebars.compile>[1]} */
     templateOptions: {
-      // ...
+      noEscape: true,
+      strict: true
     },
-    pdfOptions: {
-      // ...
+    getTemplateRenderer(options) {
+      return (template, data) => Handlebars.compile(template, options)(data);
     }
   }
 });
 
-// Dispose all instatiated resouces so the script can exit.
+// Dispose all instantiated resouces so the script can exit.
 await builder.close();
 ```