Add markdown-help command and auto-generate CLI documentation (#1518)

* Add `markdown-help` command and update CLI documentation

* Auto-generate cli.md before start, build, and publish

* Update cli.md.template

.gitignore

@@ -16,6 +16,7 @@ diff.png
 /test/symgroups.pdf
 /test/screenshotter/unicode-fonts
 coverage/
+docs/cli.md
 lib/core/metadata.js
 lib/core/MetadataBlog.js
 website/translated_docs

cli.js

@@ -20,7 +20,7 @@ try {
 const {version} = require("./package.json");
 const fs = require("fs");
 
-const options = require("commander")
+const program = require("commander")
     .version(version)
     .option("-d, --display-mode",
         "Render math in display mode, which puts the math in display style " +
@@ -60,8 +60,22 @@ const options = require("commander")
     .option("-f, --macro-file <path>",
         "Read macro definitions, one per line, from the given file.")
     .option("-i, --input <path>", "Read LaTeX input from the given file.")
-    .option("-o, --output <path>", "Write html output to the given file.")
-    .parse(process.argv);
+    .option("-o, --output <path>", "Write html output to the given file.");
+
+program.command('markdown-help')
+    .description('Print markdown version of the help')
+    .action(() => {
+        console.log();
+        console.log(program.options.map(option => `### \`${option.flags}\`
+${option.description}${((option.bool && option.defaultValue !== undefined)
+    ? ' (default: ' + option.defaultValue + ')' : '')}
+`)
+            .concat(['### `-h, --help`\nOutput usage information'])
+            .join('\n'));
+        process.exit();
+    });
+
+const options = program.parse(process.argv);
 
 
 function readMacros() {

docs/cli.md

@@ -1,58 +0,0 @@
----
-id: cli
-title: CLI
----
-
-KaTeX installed [using Node.js package managers](node.md) comes with a built-in CLI
-which can be used to render TeX to HTML from the command line. By default, CLI will
-take the input from `stdin`.
-
-```bash
-npx katex
-```
-
-> Above uses the `npx` command to run the locally installed executable.
-You can execute with the relative path: `./node_modules/.bin/katex`
-
-> To use CLI from local clone, you need to build the project first by
-running `npm run dist`
-
-# Usage
-
-## `-d, --display-mode`
-If true the math will be rendered in display mode, which will put the math in
-display style (so `\int` and `\sum` are large, for example), and will center the
-math on the page on its own line.  [false]
-
-## `-t, --no-throw-on-error`
-If true, KaTeX will throw a ParseError when it encounters an unsupported command.
-If false, KaTeX will render the unsupported command as text in the color given by
-errorColor.  [true]
-
-## `-c color, --error-color color`
-A color string given in the format 'rgb' or 'rrggbb'. This option determines the
-color which unsupported commands are rendered in.  [#cc0000]
-
-## `-b, --color-is-text-color`
-Makes \color behave like LaTeX's 2-argument \textcolor, instead of LaTeX's
-one-argument \color mode change.  [false]
-
-## `-u, --unicode-text-in-math-mode`
-Add support for unicode text characters in math mode.  [false]
-
-## `-s size, --max-size size`
-If non-zero, all user-specified sizes, e.g. in \rule{500em}{500em}, will be capped
-to maxSize ems. Otherwise, elements and spaces can be arbitrarily large  [0]
-
-## `-m macro:expansion, --macro macro:expansion`
-A custom macro. Each macro is a property with a name like \name which maps to a
-string that describes the expansion of the macro.  []
-
-## `-f path, --macro-file path`
-Read macro definitions from the given file.
-
-## `-i path, --input path`
-Read LaTeX input from the given file.
-
-## `-o path, --output path`
-Write html output to the given file.

docs/cli.md.template

@@ -0,0 +1,20 @@
+---
+id: cli
+title: CLI
+---
+
+KaTeX installed [using Node.js package managers](node.md) comes with a built-in CLI
+which can be used to render TeX to HTML from the command line. By default, CLI will
+take the input from `stdin`.
+
+```bash
+npx katex
+```
+
+> Above uses the `npx` command to run the locally installed executable.
+You can execute with the relative path: `./node_modules/.bin/katex`
+
+> To use CLI from local clone, you need to build the project first by
+running `npm run build`
+
+## Options

website/package.json

@@ -1,8 +1,9 @@
 {
   "scripts": {
+    "prestart": "cp ../docs/cli.md.template ../docs/cli.md && node ../cli.js markdown-help >> ../docs/cli.md",
     "start": "docusaurus-start",
-    "build": "docusaurus-build",
-    "publish-gh-pages": "docusaurus-publish",
+    "build": "npm run prestart && docusaurus-build",
+    "publish-gh-pages": "npm run prestart && docusaurus-publish",
     "write-translations": "docusaurus-write-translations",
     "version": "docusaurus-version",
     "rename-version": "docusaurus-rename-version"