Command Line Interface (CLI)

Markugen comes with a command line interface (CLI) that can be used in lieu of having to build a Markugen object in code. Markugen will still need to be installed into your project by using one of the following commands:

npm
yarn
pnpm

npm install markugen

yarn add markugen

pnpm add markugen

npm

npm install markugen

yarn

yarn add markugen

pnpm

pnpm add markugen

Execution

Once Markugen has been installed, you should now be able to execute the CLI via the following command:

.bash
npx markugen

Additionally, you can add markugen to your package.json as a script and use npm run to execute the script:

.json
{
  ...
  "scripts": {
    "markugen": "markugen"
  }
}

Options

Most of the options available to Markugen's constructor are also available with the CLI. There are a few options that are too complex for the command line and, therefore, are not available (i.e. themes).

All available options/arguments can be viewed by executing one of the following commands:

.bash
markugen help
# or
markugen -h
# or
markugen --help

The help option will output the following help message:

.txt
> markugen@2.0.5 start
> node --import tsx src/bin/cli.ts help

markugen

Markdown to HTML and/or PDF file generation

Commands:
  markugen html  Markdown to HTML and/or PDF file generation
                                                   [default] [aliases: mdtohtml]
  markugen pdf   HTML to PDF file generation                [aliases: htmltopdf]

Options:
      --version                       Show version number              [boolean]
  -h, --help                          Show help                        [boolean]
      --format, --input-format, --if  format of the input, string of markdown or
                                      path to file/directory
                                   [choices: "file", "string"] [default: "file"]
      --output-format, --of           format of the output, html files or string
                                      of html (string is only valid if format is
                                      also string or input is a file)
                                   [choices: "file", "string"] [default: "file"]
  -i, --input                         the directory to locate the markdown
                                      files, a single file, or a string of
                                      markdown           [string] [default: "."]
      --extensions, --exts            list of file extensions to search the
                                      input directory for
                                                       [array] [default: ["md"]]
  -o, --output                        directory to write the output
                                                           [default: "./output"]
  -n, --outputName, --on              base name of the file to output, only used
                                      when --input is a file or string, defaults
                                      to index for strings and the file name for
                                      files
  -p, --pdf                           generates PDF files instead of html files
                                                      [boolean] [default: false]
      --pdf-only, --po                implies --pdf and removes all html
                                      generated files, leaving only the PDFs
                                                      [boolean] [default: false]
  -x, --exclude                       list of files or folders to exclude from
                                      generation, paths should be relative to
                                      the input directory                [array]
  -t, --title                         the title to use for the site
                                           [string] [default: "Markugen v2.0.5"]
      --inherit-title, --it           if true, all pages not custom configured
                                      will inherit the site title      [boolean]
  -f, --footer                        overrides the default Markugen footer
                                                                        [string]
      --timestamp, --ts               if true, a timestamp will be embedded in
                                      the js output    [boolean] [default: true]
      --home, --index                 sets the home page for the site, default
                                      uses the first root page          [string]
      --toc                           maximum header depth to output in the
                                      Table of Contents, values less than or
                                      equal to zero will hide the Table of
                                      Contents.            [number] [default: 3]
  -e, --embed                         if true, css and javascript will be
                                      embedded in each page            [boolean]
      --favicon                       relative path to an icon to use as the
                                      favicon, must be relative to the input
                                      directory                         [string]
  -a, --assets                        list of files or folders to copy to the
                                      output                             [array]
  -k, --keep-assets, --ka             if true and --pdf, will keep the assets
                                      after generation[boolean] [default: false]
      --script                        additional JavaScript to embed in the
                                      script tag at the end of the body [string]
      --js                            additional JavaScript files to include on
                                      each page                          [array]
      --style                         additional CSS to embed in the style tag
                                                                        [string]
      --css                           additional CSS files to include on each
                                      page                               [array]
      --include-hidden, --ih          include folders and files that begin with
                                      a dot (.)       [boolean] [default: false]
      --clear-output, --co            clears the output folder before building
                                                      [boolean] [default: false]
  -v, --vars                          path to a JSON file representing dynamic
                                      variables used in template expansion
                                                                        [string]
      --config                        path to a JSON file with an object
                                      containing CLI arguments          [string]
  -b, --browser                       the path to the Chrome or Firefox
                                      executable. This is only required if
                                      generating PDFs and Markugen is unable to
                                      locate the executable.            [string]
      --sandbox                       turns off the use of a sandbox for Chrome,
                                      this should only be necessary if running
                                      in a container and generating PDFs
                                                       [boolean] [default: true]
  -c, --color                         if true, console output will be colored
                                                       [boolean] [default: true]
  -q, --quiet                         if given, no output will be displayed
                                                      [boolean] [default: false]
  -d, --debug                         turns on debugging
                                                      [boolean] [default: false]

Subcommands

The CLI has two subcommands that can be used: html and pdf. The subcommands have aliases as well: mdtohtml and htmltopdf respectively. The html subcommand is the default command used by the CLI; therefore, if no command is provided, it will use the html command. The options available for each subcommand can be obtained by providing the name of the command right before the help option. The following two outputs show the options available via the default html subcommand and the pdf subcommand respectively:

Markdown to HTML

.txt
> markugen@2.0.5 start
> node --import tsx src/bin/cli.ts html help

markugen html

Markdown to HTML and/or PDF file generation

Options:
      --version                       Show version number              [boolean]
  -h, --help                          Show help                        [boolean]
      --format, --input-format, --if  format of the input, string of markdown or
                                      path to file/directory
                                   [choices: "file", "string"] [default: "file"]
      --output-format, --of           format of the output, html files or string
                                      of html (string is only valid if format is
                                      also string or input is a file)
                                   [choices: "file", "string"] [default: "file"]
  -i, --input                         the directory to locate the markdown
                                      files, a single file, or a string of
                                      markdown           [string] [default: "."]
      --extensions, --exts            list of file extensions to search the
                                      input directory for
                                                       [array] [default: ["md"]]
  -o, --output                        directory to write the output
                                                           [default: "./output"]
  -n, --outputName, --on              base name of the file to output, only used
                                      when --input is a file or string, defaults
                                      to index for strings and the file name for
                                      files
  -p, --pdf                           generates PDF files instead of html files
                                                      [boolean] [default: false]
      --pdf-only, --po                implies --pdf and removes all html
                                      generated files, leaving only the PDFs
                                                      [boolean] [default: false]
  -x, --exclude                       list of files or folders to exclude from
                                      generation, paths should be relative to
                                      the input directory                [array]
  -t, --title                         the title to use for the site
                                           [string] [default: "Markugen v2.0.5"]
      --inherit-title, --it           if true, all pages not custom configured
                                      will inherit the site title      [boolean]
  -f, --footer                        overrides the default Markugen footer
                                                                        [string]
      --timestamp, --ts               if true, a timestamp will be embedded in
                                      the js output    [boolean] [default: true]
      --home, --index                 sets the home page for the site, default
                                      uses the first root page          [string]
      --toc                           maximum header depth to output in the
                                      Table of Contents, values less than or
                                      equal to zero will hide the Table of
                                      Contents.            [number] [default: 3]
  -e, --embed                         if true, css and javascript will be
                                      embedded in each page            [boolean]
      --favicon                       relative path to an icon to use as the
                                      favicon, must be relative to the input
                                      directory                         [string]
  -a, --assets                        list of files or folders to copy to the
                                      output                             [array]
  -k, --keep-assets, --ka             if true and --pdf, will keep the assets
                                      after generation[boolean] [default: false]
      --script                        additional JavaScript to embed in the
                                      script tag at the end of the body [string]
      --js                            additional JavaScript files to include on
                                      each page                          [array]
      --style                         additional CSS to embed in the style tag
                                                                        [string]
      --css                           additional CSS files to include on each
                                      page                               [array]
      --include-hidden, --ih          include folders and files that begin with
                                      a dot (.)       [boolean] [default: false]
      --clear-output, --co            clears the output folder before building
                                                      [boolean] [default: false]
  -v, --vars                          path to a JSON file representing dynamic
                                      variables used in template expansion
                                                                        [string]
      --config                        path to a JSON file with an object
                                      containing CLI arguments          [string]
  -b, --browser                       the path to the Chrome or Firefox
                                      executable. This is only required if
                                      generating PDFs and Markugen is unable to
                                      locate the executable.            [string]
      --sandbox                       turns off the use of a sandbox for Chrome,
                                      this should only be necessary if running
                                      in a container and generating PDFs
                                                       [boolean] [default: true]
  -c, --color                         if true, console output will be colored
                                                       [boolean] [default: true]
  -q, --quiet                         if given, no output will be displayed
                                                      [boolean] [default: false]
  -d, --debug                         turns on debugging
                                                      [boolean] [default: false]

HTML to PDF

.txt
> markugen@2.0.5 start
> node --import tsx src/bin/cli.ts pdf help

markugen pdf

HTML to PDF file generation

Options:
      --version             Show version number                        [boolean]
  -h, --help                Show help                                  [boolean]
  -i, --input               the directory to locate the markdown files, a single
                            file, or a string of markdown    [string] [required]
      --extensions, --exts  list of file extensions to search the input
                            directory for            [array] [default: ["html"]]
  -l, --links               if true, markdown links generated by Markugen will
                            be converted to PDF links  [boolean] [default: true]
  -b, --browser             the path to the Chrome or Firefox executable. This
                            is only required if generating PDFs and Markugen is
                            unable to locate the executable.            [string]
      --sandbox             turns off the use of a sandbox for Chrome, this
                            should only be necessary if running in a container
                            and generating PDFs        [boolean] [default: true]
  -c, --color               if true, console output will be colored
                                                       [boolean] [default: true]
  -q, --quiet               if given, no output will be displayed
                                                      [boolean] [default: false]
  -d, --debug               turns on debugging        [boolean] [default: false]