Skip to content

Commit

Permalink
Reorganize MarkBind installation instructions in UG (#2366)
Browse files Browse the repository at this point in the history
  • Loading branch information
@tlylt
tlylt authored Sep 9, 2023
1 parent 102cad1 commit 4dd8d72
Show file tree
Hide file tree
Showing 2 changed files with 150 additions and 60 deletions.
7 changes: 7 additions & 0 deletions docs/userGuide/cliCommands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,13 @@

### Overview

<box type="info" seamless>

If you do not have MarkBind installed globally, you can still use MarkBind commands by prefixing the commands with `npx`. For example, `markbind init` becomes `npx markbind-cli init`.

If you have MarkBind installed locally, you may also refer to the scripts section of your `package.json` file for the commands you can use. For example, `npm run init` for `markbind init`.
</box>

An overview of MarkBind's Command Line Interface (CLI) can be referenced with `markbind --help`:
```
$ markbind --help
Expand Down
203 changes: 143 additions & 60 deletions docs/userGuide/gettingStarted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
<frontmatter>
title: "User Guide - {{ title }}"
layout: userGuide.md
pageNav: 2
</frontmatter>

# {{ title }}
Expand All @@ -18,34 +19,21 @@
%%{{ icon_ticked }}%% [Node.js](https://nodejs.org) {{ node_version }} or higher installed
</div>

<box type="tip" header="##### Quick Start :rocket:" >
There are a few ways to install MarkBind, select one that is most suitable for your use case. If you are unsure, we recommend using the first method.

Initialize a MarkBind site:
## Method 1: Install MarkBind globally with npm

```
npx markbind-cli init mySite
```

Preview the site:

```
cd mySite
npx markbind-cli serve
```

See usage information:

```
npx markbind-cli --help
```
<box type="info" seamless>

This method is recommended for most users. It allows you to use MarkBind commands directly in your terminal, particularly useful if you have multiple MarkBind sites.
</box>

++**1. Install MarkBind**++

Run the following command to install MarkBind.
Run the following command to install MarkBind globally. This will make the `markbind` command available in your terminal.

```
$ npm install -g markbind-cli
npm install -g markbind-cli
```

Next, run the command `markbind`. If MarkBind has been installed correctly, you should see the MarkBind ascii logo followed by a summary of MarkBind commands as the output.
Expand All @@ -58,20 +46,104 @@ $ markbind
| | | | | (_| | | | | < | |_) | | | | | | | | (_| |
|_| |_| \__,_| |_| |_|\_\ |____/ |_| |_| |_| \__,_|
v3.x.y
v5.x.y
Usage: ...
```

<panel header="Alternative installation: as a local dev-dependency with `package.json`">
++**2. Initialize a new Project (or Start with an existing Project)**++

<tabs>
<tab header="Initializing a new project">

Navigate into an empty directory and run the following command to initialize a skeletal MarkBind site in that directory. It will create several new files in the directory e.g., `index.md`, `site.json`.

```
markbind init
```

<include src="tip.md" boilerplate >
<span id="tip_body">
You can add the `--help` flag to any command to show the help screen. <br>
e.g., `markbind init --help`
</span>
</include>
<include src="tip.md" boilerplate >
<span id="tip_body">
The `init` command populates the project with the [default project template](https://markbind-init-typical.netlify.com/). Refer to [templates](templates.html) section to learn how to use a different template.
</span>
</include>

</tab>
<tab header="Starting with an existing project">

Navigate to the project {{ tooltip_root_directory }}.

</tab>
</tabs>

++**3. Preview the site**++

Run the following command in the same directory. It will generate a website from your source files, start a web server, and open a <trigger trigger="click" for="modal:quickStart-livePreview">live preview</trigger> of your site in your default Browser.

<modal large header="Live Preview" id="modal:quickStart-livePreview">
<include src="glossary.md#live-preview"/>
</modal>

```
markbind serve
```

Do some changes to the `index.md` and save the file. The live preview in the Browser should update automatically to reflect your changes.

To stop the web server, go to the console running the `serve` command and press <kbd>CTRL</kbd> + <kbd>C</kbd> (or the equivalent in your OS).

<div id="instruction-next-steps">

++**4. Next steps**++

1. **Update the content of your site**. More info can be found in the [_User Guide: Authoring Contents_](authoringContents.html) section
1. **Deploy your site**. More info can be found in the [_User Guide: Deploying the Site_](deployingTheSite.html) section.

</div>

++**5. Updating your MarkBind version**++

After you have installed MarkBind, you may want to update to the latest version of MarkBind in the future.

```
npm install -g markbind-cli@latest
```

To update to a specific version of MarkBind, replace `latest` with the version number e.g., `5.0.2`.

```
npm install -g [email protected]
```

If you are using any CI/CD tools, ensure the version of MarkBind is updated in the CI/CD pipeline as well.
- For example, update your GitHub Actions workflow file to use the correct version of MarkBind, if you are using [markbind-action](https://github.com/MarkBind/markbind-action).

---

## Method 2: Install MarkBind locally as a dev-dependency in `package.json`

<box type="info" seamless>

This method is recommended if you
- are creating a documentation site that more than one person will be working on
- want to specify the version of MarkBind to use in your project and manage it via `package.json`
</box>

++**1. Initialize a `package.json` file**++

:glyphicon-hand-right: _If you already have a `package.json` file, skip to the next step._
:glyphicon-hand-right: _If you already have a `package.json` file, skip to step 2._

:glyphicon-hand-right: _If you are working on a MarkBind project that is set up with this method, run `npm ci` to install the dependencies and refer to step 3 for how to run MarkBind commands._

To initialize a npm project in your current working directory, run the following command.

```
$ npm init
npm init
```
You will need to answer the prompts to create a `package.json` file.

Expand All @@ -80,7 +152,7 @@ You will need to answer the prompts to create a `package.json` file.
To get a default `package.json` file, run the following command.

```
$ npm init -y
npm init -y
```

You can always adjust the content of your `package.json` later.
Expand All @@ -90,7 +162,7 @@ You can always adjust the content of your `package.json` later.
++**2. Install markbind-cli locally as a dev-dependency**++

```
$ npm install markbind-cli --save-dev
npm install markbind-cli --save-dev
```

++**3. Add scripts in the `package.json` file**++
Expand All @@ -115,61 +187,72 @@ You are now ready to run MarkBind commands with `npm run xxx` (e.g. `npm run ini
If you are using Git to version control your source files, view the [_User Guide: .gitignore File_](gitignoreFile.html) section for more info.
</box>

</panel>
<include src="gettingStarted.md#instruction-next-steps" />

<br>
++**5. Updating your MarkBind version**++

++**2. Initialize a new Project (or Start with an existing Project)**++
After you have installed MarkBind, you may want to update to the latest version of MarkBind in the future.

<tabs>
<tab header="Initializing a new project">
Go to your project directory that contains the `package.json` file and run the following command.

Navigate into an empty directory and run the following command to initialize a skeletal MarkBind site in that directory. It will create several new files in the directory e.g., `index.md`, `site.json`.
```
npm install markbind-cli@latest --save-dev
```

To update to a specific version of MarkBind, replace `latest` with the version number e.g., `5.0.2`.

```
$ markbind init
npm install markbind[email protected] --save-dev
```

<include src="tip.md" boilerplate >
<span id="tip_body">
You can add the `--help` flag to any command to show the help screen. <br>
e.g., `markbind init --help`
</span>
</include>
<include src="tip.md" boilerplate >
<span id="tip_body">
The `init` command populates the project with the [default project template](https://markbind-init-typical.netlify.com/). Refer to [templates](templates.html) section to learn how to use a different template.
</span>
</include>
If you are using any CI/CD tools, ensure the version of MarkBind is updated in the CI/CD pipeline as well.
- For example, update your GitHub Actions workflow file to use the correct version of MarkBind, if you are using [markbind-action](https://github.com/MarkBind/markbind-action).

</tab>
<tab header="Starting with an existing project">
The command will modify your `package.json` and `package-lock.json` file to update the version of MarkBind.

Navigate to the project {{ tooltip_root_directory }}.
---

</tab>
</tabs>
## Method 3: Install MarkBind via npx

++**3. Preview the site**++
<box type="info" seamless>

Run the following command in the same directory. It will generate a website from your source files, start a web server, and open a <trigger trigger="click" for="modal:quickStart-livePreview">live preview</trigger> of your site in your default Browser.
This method is recommended if you want to try out MarkBind without installing it (by using <tooltip content="NPX stands for Node Package eXecute. It is simply an NPM package runner. It allows developers to execute any Javascript Package available on the NPM registry without even installing it.">[npx](https://docs.npmjs.com/cli/commands/npx)</tooltip>).
</box>

<modal large header="Live Preview" id="modal:quickStart-livePreview">
<include src="glossary.md#live-preview"/>
</modal>
++**1. Initialize a MarkBind site**++

```
$ markbind serve
npx markbind-cli init mySite
```

Do some changes to the `index.md` and save the file. The live preview in the Browser should update automatically to reflect your changes.
++**2. Preview the site**++

To stop the web server, go to the console running the `serve` command and press <kbd>CTRL</kbd> + <kbd>C</kbd> (or the equivalent in your OS).
```
cd mySite
npx markbind-cli serve
```

++**4. Next steps**++
++**3. See usage information**++

1. **Update the content of your site**. More info can be found in the [_User Guide: Authoring Contents_](authoringContents.html) section
1. **Deploy your site**. More info can be found in the [_User Guide: Deploying the Site_](deployingTheSite.html) section.
```
npx markbind-cli --help
```

<include src="gettingStarted.md#instruction-next-steps" />

++**5. Updating your MarkBind version**++

To use the latest version of MarkBind in the future, specify `latest` in the command.

```
npx markbind-cli@latest init mySite
```

Or, specify the version number.

```
npx [email protected] init mySite
```

{% from "njk/common.njk" import previous_next %}
{{ previous_next('', 'authoringContents') }}

0 comments on commit 4dd8d72

Please sign in to comment.