showdown/docs/cli.md

Showdown comes bundled with a Command-line interface (CLI) tool that allows you to run Showdown converter from the command line.

Requirements

• Node.js

Quick start guide

1. Check that Showdown CLI is accessible.

   • If you installed Showdown globally via npm install showdown -g, you can access the CLI tool help by typing showdown -h in the command line:

     === "input"

       ```sh
       showdown -h
       ```
     

     === "output"

       ```
       Usage: showdown <command> [options]
     
       CLI to Showdownjs markdown parser v3.0.0-alpha
     
       Options:
         -V, --version       output the version number
         -q, --quiet         Quiet mode. Only print errors
         -m, --mute          Mute mode. Does not print anything
         -h, --help          display help for command
     
       Commands:
         makehtml [options]  Converts markdown into html
         help [command]      display help for command
       ```
     

   • If you installed Showdown locally via npm install showdown, open the folder where Showdown is installed, and type node ./bin/showdown.js -h in the command line:

     === "input"

       ```sh
       node ./bin/showdown.js -h
       ```
     

     === "output"

       ```
       Usage: showdown <command> [options]
     
       CLI to Showdownjs markdown parser v3.0.0-alpha
     
       Options:
         -V, --version       output the version number
         -q, --quiet         Quiet mode. Only print errors
         -m, --mute          Mute mode. Does not print anything
         -h, --help          display help for command
     
       Commands:
         makehtml [options]  Converts markdown into html
         help [command]      display help for command
       ```
     

2. Use makehtml command to convert your document to HTML. For example:

   !!! example "Convert foo.md into bar.html"

    ```sh
    showdown makehtml -i foo.md -o bar.html
    ```
   

Commands

makehtml

Convert a Markdown input into HTML.

Usage

showdown makehtml [options]

Options

-i / --input

• Short format: -i

• Alias: --input

• Description: Input source. Usually a .md file. If omitted or empty, reads from stdin.

• Examples:

  !!! example ""

    ```sh
    // Read from stdin and output to stdout
    showdown makehtml -i
  
    // Read from the foo.md file and output to stdout
    showdown makehtml --input foo.md
    ```
  

-o/--output

• Short format: -o

• Alias: --output

• Description: Output target. Usually a .html file. If omitted or empty, writes to stdout.

• Example:

  !!! example ""

    ```sh
    // Read from the foo.md file and output to bar.html
    showdown makehtml -i foo.md -o bar.html
    ```
  

-a/--append

• Short format: -a

• Alias: --append

• Description: Append data to output instead of overwriting.

• Example:

  !!! example ""

    ```sh
    showdown makehtml -a
    ```
  

-u/--encoding

• Short format: -u

• Alias: --encoding

• Description: Specify the input encoding.

• Example:

  !!! example ""

    ```sh
    showdown makehtml -u UTF8
    ```
  

-e/--extensions

• Short format: -e

• Alias: --extension

• Description: Load the specified extension(s). Should be valid path(s) to Node-compatible extensions.

• Example:

  !!! example ""

    ```sh
    showdown makehtml -e ~/twitter.js -e ~/youtube.js
    ```
  

-c/--config

• Short format: -c

• Alias: --config

• Description: Enable or disable parser options.

• Introduced in: 2.0.1 (Breaking change. See the Extra options section below)

• Example:

  !!! example ""

    ```sh
    showdown makehtml -i foo.md -o bar.html -c strikethrough
    showdown makehtml -i foo.md -o bar.html -c strikethrough -c emoji
    ```
  

Extra options

Starting from the version 2.0.1, CLI the format of passing extra options has changed. Please make the necessary changes to your code, if required.

=== "since v2.0.1"

```sh
showdown makehtml -i foo.md -o bar.html -c strikethrough -c emoji
```

=== "before v2.0.1"

```sh
showdown makehtml -i foo.md -o bar.html --strikethrough --emoji
```

You can specify any of the supported options, and they will be passed to the converter.

The above commands are equivalent of doing:

var conv = new showdown.Converter({strikethrough: true, emoji: true});

!!! warning "" In the CLI tool, all the extra options are disabled by default. This is the opposite of what is defined for node and browser, where some options, like ghCodeBlocks are enabled (for backward compatibility and historical reasons).