Skip to content

Commit

Permalink
Add help usage to user guide (#996)
Browse files Browse the repository at this point in the history
  • Loading branch information
@madanalogy
madanalogy authored Feb 6, 2020
1 parent c3aac49 commit 6b44e3c
Show file tree
Hide file tree
Showing 2 changed files with 103 additions and 81 deletions.
148 changes: 85 additions & 63 deletions docs/userGuide/cliCommands.md
View file
Original file line number Diff line number Diff line change
@@ -1,82 +1,43 @@
<frontmatter>
title: "User Guide: Command Line Interface (CLI)"
layout: userGuide
pageNav: default
</frontmatter>

# MarkBind CLI

### Overview

MarkBind Command Line Interface (CLI) can be run in the following ways:

* `markbind [--version | -v]`<br>
Prints the version number of the MarkBind installation in use.<br>
{{ icon_examples }} `markbind --version`, `markbind -v`
* `markbind [--help | -h]`<br>
Prints a summary of MarkBind commands.<br>
{{ icon_examples }} `markbind --help`, `markbind -h`
* `markbind <command> [--help | -h]`
Print instructions specific to the given `<command>`.<br>
{{ icon_examples }} `markbind build -h` %%(prints instructions for the `build` command)%%
* `markbind <command> [<args>]`<br>
Executes the given `<command>` with the given arguments. Available commands are described in the sections below.

<hr><!-- ========================================================================== -->

### `build` Command

**Format:** `markbind build [<OPTIONS>]`<br>
**Alias:** `markbind b`

**Description:** Generates the site to the directory named `_site` in the current directory.

**`OPTIONS`:**
* `<output>`<br>
Put the generated files in the specified directory<br>
{{ icon_example }} `../myOutDir`
* `<root> <output>`<br>
Read source files from the `<root>` directory and put the generated files in the specified `<output>` directory<br>
{{ icon_example }} `./myWebsite ../myOutDir`
* `--baseUrl <base>`<br>
Override the `baseUrl` property (read from the `site.json`) with the give `<base>` value.<br>
{{ icon_example }} `--baseUrl staging`
* `-s <file>`, `--site-config <file>`<br>
Specify the site config file (default: `site.json`)<br>
{{ icon_example }} `-s otherSite.json`

**{{ icon_examples }}**
* `markbind build`
* `markbind build ./myWebsite ./myOutDir`
* `markbind build ./stagingDir --baseUrl staging`
<hr><!-- ========================================================================== -->

### `deploy` Command

**Format:** `markbind deploy [<OPTIONS>]`<br>
**Alias:** `markbind d`

**Description:** Deploys the site to the repo's Github pages by pushing everything in the generated site (default dir: `_site`) to the `gh-pages` branch of the current git working directory's remote repo.

**`OPTIONS`:**
* `-t <githubTokenName>`, `--travis <githubTokenName>`<br>
Deploy the site in Travis CI using the GitHub personal access token stored in `<githubTokenName>`. (default: `GITHUB_TOKEN`)<br>
{{ icon_example }} `-t PA_TOKEN`

%%{{ icon_info }} Related: [User Guide: Deploying the Website](deployingTheSite.html).%%

An overview of MarkBind's Command Line Interface (CLI) can be referenced with `markbind --help`:
```
$ markbind --help
Usage: markbind <command>
Options:
-V, --version output the version number
-h, --help output usage information
Commands:
init|i [options] [root] init a markbind website project
serve|s [options] [root] build then serve a website from a directory
build|b [options] [root] [output] build a website
deploy|d [options] deploy the site to the repo's Github pages
```
<hr><!-- ========================================================================== -->

### `init` Command

**Format:** `markbind init [<OPTIONS>]`<br>
**Format:** `markbind init [options] [root]`<br>
**Alias:** `markbind i`

**Description:** Initializes a directory into a MarkBind site by creating a skeleton structure for the website which includes a `index.md` and a `site.json`.

**`OPTIONS`:**
* `<root>`<br>
**Arguments:**
* `[root]`<br>
Root directory. Default is the current directory.<br>
{{ icon_example }} `./myWebsite`

**`options`:**
* `-c`, `--convert`<br>
Convert an existing GitHub wiki or `docs` folder into a MarkBind website. See [Converting an existing Github project]({{ baseUrl }}/userGuide/markBindInTheProjectWorkflow.html#converting-existing-project-documentation-wiki) for more information.

Expand All @@ -89,7 +50,7 @@ MarkBind Command Line Interface (CLI) can be run in the following ways:

### `serve` Command

**Format:** `markbind serve [<OPTIONS>]`<br>
**Format:** `markbind serve [options] [root]`<br>
**Alias:** `markbind s`

**Description:** Does the following steps:
Expand All @@ -101,10 +62,12 @@ MarkBind Command Line Interface (CLI) can be run in the following ways:
<include src="glossary.md#live-preview" inline/>
</modal>

**`OPTIONS`:**
* `<root>`<br>
**Arguments:**
* `[root]`<br>
Root directory. Default is the current directory.<br>
{{ icon_example }} `./myWebsite`

**`options`:**
* `-f`, `--force-reload`<br>
Force live reload to process all files in the site, instead of just the relevant files. This option is useful when you are modifying a file that is not a file type monitored by the <trigger trigger="click" for="modal:cliCommands-livePreview">live preview</trigger> feature.
* `-n`, `--no-open`<br>
Expand All @@ -122,3 +85,62 @@ MarkBind Command Line Interface (CLI) can be run in the following ways:
* `markbind serve`
* `markbind serve ./myWebsite`
* `markbind serve -p 8888 -s otherSite.json`

<hr><!-- ========================================================================== -->

### `build` Command

**Format:** `markbind build [options] [root] [output]`<br>
**Alias:** `markbind b`

**Description:** Generates the site to the directory named `_site` in the current directory.

**Arguments:**
* `[output]`<br>
Put the generated files in the specified directory<br>
{{ icon_example }} `../myOutDir`
* `[root] [output]`<br>
Read source files from the `[root]` directory and put the generated files in the specified `[output]` directory<br>
{{ icon_example }} `./myWebsite ../myOutDir`

**`options`:**
* `--baseUrl <base>`<br>
Override the `baseUrl` property (read from the `site.json`) with the give `<base>` value.<br>
{{ icon_example }} `--baseUrl staging`
* `-s <file>`, `--site-config <file>`<br>
Specify the site config file (default: `site.json`)<br>
{{ icon_example }} `-s otherSite.json`

**{{ icon_examples }}**
* `markbind build`
* `markbind build ./myWebsite ./myOutDir`
* `markbind build ./stagingDir --baseUrl staging`

<hr><!-- ========================================================================== -->

### `deploy` Command

**Format:** `markbind deploy [options]`<br>
**Alias:** `markbind d`

**Description:** Deploys the site to the repo's Github pages by pushing everything in the generated site (default dir: `_site`) to the `gh-pages` branch of the current git working directory's remote repo.

**`options`:**
* `-t <githubTokenName>`, `--travis <githubTokenName>`<br>
Deploy the site in Travis CI using the GitHub personal access token stored in `<githubTokenName>`. (default: `GITHUB_TOKEN`)<br>
{{ icon_example }} `-t PA_TOKEN`

%%{{ icon_info }} Related: [User Guide: Deploying the Website](deployingTheSite.html).%%

<hr><!-- ========================================================================== -->

### `--help` Option

**Format:** `markbind [command] --help`<br>
**Alias:** `markbind [command] -h`

**Description:** Prints a summary of MarkBind commands or a detailed usage guide for the given `command`.

{{ icon_examples }}
* `markbind --help` : Prints a summary of MarkBind commands.
* `markbind serve --help` : Prints a detailed usage guide for the `serve` command.
36 changes: 18 additions & 18 deletions index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ program.outputHelp = function (cb) {

program
.allowUnknownOption()
.usage(' <command>');
.usage('<command>');

program
.name('markbind')
Expand Down Expand Up @@ -197,23 +197,6 @@ program
.catch(handleError);
});

program
.command('deploy')
.alias('d')
.description('deploy the site to the repo\'s Github pages.')
.option('-t, --travis [tokenVar]', 'deploy the site in Travis [GITHUB_TOKEN]')
.option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
.action((options) => {
const rootFolder = path.resolve(process.cwd());
const outputRoot = path.join(rootFolder, '_site');
new Site(rootFolder, outputRoot, undefined, undefined, options.siteConfig).deploy(options.travis)
.then(() => {
logger.info('Deployed!');
})
.catch(handleError);
printHeader();
});

program
.command('build [root] [output]')
.alias('b')
Expand Down Expand Up @@ -241,6 +224,23 @@ program
.catch(handleError);
});

program
.command('deploy')
.alias('d')
.description('deploy the site to the repo\'s Github pages')
.option('-t, --travis [tokenVar]', 'deploy the site in Travis [GITHUB_TOKEN]')
.option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
.action((options) => {
const rootFolder = path.resolve(process.cwd());
const outputRoot = path.join(rootFolder, '_site');
new Site(rootFolder, outputRoot, undefined, undefined, options.siteConfig).deploy(options.travis)
.then(() => {
logger.info('Deployed!');
})
.catch(handleError);
printHeader();
});

program.parse(process.argv);

if (!program.args.length
Expand Down

0 comments on commit 6b44e3c

Please sign in to comment.