Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add help usage to user guide #996

Merged
merged 1 commit into from
Feb 6, 2020
Merged

Add help usage to user guide #996

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 86 additions & 64 deletions docs/userGuide/cliCommands.md
View file
Open in desktop
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,22 +50,24 @@ 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:
1. Builds the site and puts the generated files in a directory named `_site`.
1. Starts a web server instance locally and makes the site available at `http://127.0.0.1:8080`.
1. Opens a <trigger trigger="click" for="modal:cliCommands-livePreview">live preview</trigger> of the website.

<modal large title="Live Preview" id="modal:cliCommands-livePreview">
<modal large header="Live Preview" id="modal:cliCommands-livePreview">
<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
madanalogy marked this conversation as resolved.
Show resolved Hide resolved

**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
Open in desktop
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