mirror of
https://github.com/showdownjs/showdown.git
synced 2024-03-22 13:30:55 +08:00
197 lines
4.9 KiB
Markdown
197 lines
4.9 KiB
Markdown
Showdown comes bundled with a Command-line interface (CLI) tool that allows you to run Showdown converter from the command line.
|
|
|
|
## Requirements
|
|
|
|
* [Node.js](https://nodejs.org/en/)
|
|
|
|
## 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
|
|
```
|
|
|
|
1. 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**
|
|
|
|
```sh
|
|
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`](#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](available-options.md), and they will be passed to the converter.
|
|
|
|
The above commands are equivalent of doing:
|
|
|
|
```js
|
|
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).
|