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

Reorganize MarkBind installation instructions in UG #2366

Merged
merged 3 commits into from
Sep 9, 2023
Merged

Reorganize MarkBind installation instructions in UG #2366

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3b484bf
update docs
tlylt Sep 9, 2023
109e435
add more details
tlylt Sep 9, 2023
e984b00
add update version guide
tlylt Sep 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/userGuide/cliCommands.md
View file
Open in desktop
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
Open in desktop
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 markbind-cli@5.0.2
```

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-cli@5.0.2 --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 markbind-cli@5.0.2 init mySite
```

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