From 4dd8d727e496451de2b041b96d06999ca46be986 Mon Sep 17 00:00:00 2001 From: Liu Yongliang <41845017+tlylt@users.noreply.github.com> Date: Sat, 9 Sep 2023 19:34:54 +0800 Subject: [PATCH] Reorganize MarkBind installation instructions in UG (#2366) --- docs/userGuide/cliCommands.md | 7 ++ docs/userGuide/gettingStarted.md | 203 ++++++++++++++++++++++--------- 2 files changed, 150 insertions(+), 60 deletions(-) diff --git a/docs/userGuide/cliCommands.md b/docs/userGuide/cliCommands.md index 128f88e50f..d6031208e6 100644 --- a/docs/userGuide/cliCommands.md +++ b/docs/userGuide/cliCommands.md @@ -10,6 +10,13 @@ ### Overview + + +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`. + + An overview of MarkBind's Command Line Interface (CLI) can be referenced with `markbind --help`: ``` $ markbind --help diff --git a/docs/userGuide/gettingStarted.md b/docs/userGuide/gettingStarted.md index 7ceb1e4291..6c7b0fcdcf 100644 --- a/docs/userGuide/gettingStarted.md +++ b/docs/userGuide/gettingStarted.md @@ -4,6 +4,7 @@ title: "User Guide - {{ title }}" layout: userGuide.md + pageNav: 2 # {{ title }} @@ -18,34 +19,21 @@ %%{{ icon_ticked }}%% [Node.js](https://nodejs.org) {{ node_version }} or higher installed - +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 -``` + +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. ++**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. @@ -58,20 +46,104 @@ $ markbind | | | | | (_| | | | | < | |_) | | | | | | | | (_| | |_| |_| \__,_| |_| |_|\_\ |____/ |_| |_| |_| \__,_| - v3.x.y + v5.x.y Usage: ... ``` - +++**2. Initialize a new Project (or Start with an existing 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 +``` + + + +You can add the `--help` flag to any command to show the help screen.
+ e.g., `markbind init --help` + + + + +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. + + + + + + +Navigate to the project {{ tooltip_root_directory }}. + + + + +++**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 live preview of your site in your default Browser. + + + + + +``` +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 CTRL + C (or the equivalent in your OS). + +
+ +++**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. + +
+ +++**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` + + + +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` + ++**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. @@ -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. @@ -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**++ @@ -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. - + -
+++**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. - - +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 ``` - - -You can add the `--help` flag to any command to show the help screen.
- e.g., `markbind init --help` - - - - -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. - - +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). - - +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 }}. +--- - - +## Method 3: Install MarkBind via npx -++**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 live preview of your site in your default Browser. +This method is recommended if you want to try out MarkBind without installing it (by using [npx](https://docs.npmjs.com/cli/commands/npx)). + - - - +++**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 CTRL + C (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 +``` + + + +++**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') }}