feat(cli): expose watchOptions

Closes #84.

Author: simonhaenisch

readme.md

@@ -55,6 +55,7 @@ Options:
   -h, --help ............... Output usage information
   -v, --version ............ Output version
   -w, --watch .............. Watch the current file(s) for changes
+  --watch-options .......... Options for Chokidar's watch call
   --basedir ................ Base directory to be served by the file server
   --stylesheet ............. Path to a local or remote stylesheet (can be passed multiple times)
   --css .................... String of styles
@@ -90,6 +91,12 @@ _Tip: You can concatenate multiple files using `cat file1.md file2.md`._
 
 The current working directory (`process.cwd()`) serves as the base directory of the file server by default. This can be adjusted with the `--basedir` flag (or equivalent config option).
 
+#### Watch Mode
+
+Watch mode (`--watch`) uses Chokidar's `watch` method on the markdown file. If you're having issues, you can adjust the watch options via the config (`watch_options`) or `--watch-options` CLI arg. The `awaitWriteFinish` option might be particularly useful if you use editor plugins (e. g. TOC generators) that modify and save the file after the initial save. Check out the [Chokidar docs](https://github.com/paulmillr/chokidar#api) for a full list of options.
+
+Note that Preview on macOS does not automatically reload the preview when the file has changed (or at least not reliably). There are PDF viewers available that can check for file changes and offer auto-reload (e. g. [Skim](https://skim-app.sourceforge.io/)'s "Sync" feature).
+
 #### Programmatic API
 
 The programmatic API is very simple: it only exposes one function that accepts either a `path` to or `content` of a markdown file, and an optional config object (which can be used to specify the output file destination).

src/cli.ts

@@ -5,7 +5,7 @@
 
 import arg from 'arg';
 import chalk from 'chalk';
-import { watch } from 'chokidar';
+import { watch, WatchOptions } from 'chokidar';
 import getPort from 'get-port';
 import getStdin from 'get-stdin';
 import Listr from 'listr';
@@ -26,6 +26,7 @@ export const cliFlags = arg({
 	'--version': Boolean,
 	'--basedir': String,
 	'--watch': Boolean,
+	'--watch-options': String,
 	'--stylesheet': [String],
 	'--css': String,
 	'--body-class': [String],
@@ -144,7 +145,11 @@ async function main(args: typeof cliFlags, config: Config) {
 			if (args['--watch']) {
 				console.log(chalk.bgBlue('\n watching for changes \n'));
 
-				watch(files).on('change', async (file) =>
+				const watchOptions = args['--watch-options']
+					? (JSON.parse(args['--watch-options']) as WatchOptions)
+					: config.watch_options;
+
+				watch(files, watchOptions).on('change', async (file) =>
 					new Listr([getListrTask(file)], { exitOnError: false }).run().catch(console.error),
 				);
 			} else {

src/lib/config.ts

@@ -1,3 +1,4 @@
+import { WatchOptions } from 'chokidar';
 import { MarkedOptions } from 'marked';
 import { resolve } from 'path';
 import { LaunchOptions, PDFOptions, ScriptTagOptions } from 'puppeteer';
@@ -133,4 +134,11 @@ interface BasicConfig {
 	 * Port to run the local server on.
 	 */
 	port?: number;
+
+	/**
+	 * Options to pass to Chokidar's `watch` call.
+	 *
+	 * This is specifically useful when running into issues when editor plugins trigger additional saves after the initial save.
+	 */
+	watch_options?: WatchOptions;
 }

src/lib/help.ts

@@ -8,6 +8,7 @@ const helpText = `
     -h, --help ${chalk.dim('...............')} Output usage information
     -v, --version ${chalk.dim('............')} Output version
     -w, --watch ${chalk.dim('..............')} Watch the current file(s) for changes
+		--watch-options ${chalk.dim('..........')} Options for Chokidar's watch call
     --basedir ${chalk.dim('................')} Base directory to be served by the file server
     --stylesheet ${chalk.dim('.............')} Path to a local or remote stylesheet (can be passed multiple times)
     --css ${chalk.dim('....................')} String of styles
@@ -38,6 +39,14 @@ const helpText = `
 
     ${chalk.cyan('$ md2pdf ./**/*.md')}
 
+  ${chalk.gray('–')} Convert and enable watch mode
+
+    ${chalk.cyan('$ md2pdf ./*.md --watch')}
+
+  ${chalk.gray('–')} Convert and enable watch mode with custom options
+
+    ${chalk.cyan('$ md2pdf ./*.md --watch --watch-options \'{ "atomic": true }\'')}
+
   ${chalk.gray('–')} Convert path/to/file.md with a different base directory
 
     ${chalk.cyan('$ md2pdf path/to/file.md --basedir path')}