You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/userGuide/cliCommands.md
+7Lines changed: 7 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -10,6 +10,13 @@
10
10
11
11
### Overview
12
12
13
+
<boxtype="info"seamless>
14
+
15
+
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`.
16
+
17
+
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`.
18
+
</box>
19
+
13
20
An overview of MarkBind's Command Line Interface (CLI) can be referenced with `markbind --help`:
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.
22
23
23
-
Initialize a MarkBind site:
24
+
## Method 1: Install MarkBind globally with npm
24
25
25
-
```
26
-
npx markbind-cli init mySite
27
-
```
28
-
29
-
Preview the site:
30
-
31
-
```
32
-
cd mySite
33
-
npx markbind-cli serve
34
-
```
35
-
36
-
See usage information:
37
-
38
-
```
39
-
npx markbind-cli --help
40
-
```
26
+
<boxtype="info"seamless>
41
27
28
+
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.
42
29
</box>
43
30
44
31
++**1. Install MarkBind**++
45
32
46
-
Run the following command to install MarkBind.
33
+
Run the following command to install MarkBind globally. This will make the `markbind` command available in your terminal.
34
+
47
35
```
48
-
$ npm install -g markbind-cli
36
+
npm install -g markbind-cli
49
37
```
50
38
51
39
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.
<panelheader="Alternative installation: as a local dev-dependency with `package.json`">
53
+
++**2. Initialize a new Project (or Start with an existing Project)**++
54
+
55
+
<tabs>
56
+
<tabheader="Initializing a new project">
57
+
58
+
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`.
59
+
60
+
```
61
+
markbind init
62
+
```
63
+
64
+
<includesrc="tip.md"boilerplate >
65
+
<spanid="tip_body">
66
+
You can add the `--help` flag to any command to show the help screen. <br>
67
+
e.g., `markbind init --help`
68
+
</span>
69
+
</include>
70
+
<includesrc="tip.md"boilerplate >
71
+
<spanid="tip_body">
72
+
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.
73
+
</span>
74
+
</include>
75
+
76
+
</tab>
77
+
<tabheader="Starting with an existing project">
78
+
79
+
Navigate to the project {{ tooltip_root_directory }}.
80
+
81
+
</tab>
82
+
</tabs>
83
+
84
+
++**3. Preview the site**++
85
+
86
+
Run the following command in the same directory. It will generate a website from your source files, start a web server, and open a <triggertrigger="click"for="modal:quickStart-livePreview">live preview</trigger> of your site in your default Browser.
Do some changes to the `index.md` and save the file. The live preview in the Browser should update automatically to reflect your changes.
97
+
98
+
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).
99
+
100
+
<divid="instruction-next-steps">
101
+
102
+
++**4. Next steps**++
103
+
104
+
1.**Update the content of your site**. More info can be found in the [_User Guide: Authoring Contents_](authoringContents.html) section
105
+
1.**Deploy your site**. More info can be found in the [_User Guide: Deploying the Site_](deployingTheSite.html) section.
106
+
107
+
</div>
108
+
109
+
++**5. Updating your MarkBind version**++
110
+
111
+
After you have installed MarkBind, you may want to update to the latest version of MarkBind in the future.
112
+
113
+
```
114
+
npm install -g markbind-cli@latest
115
+
```
116
+
117
+
To update to a specific version of MarkBind, replace `latest` with the version number e.g., `5.0.2`.
118
+
119
+
```
120
+
npm install -g markbind-cli@5.0.2
121
+
```
122
+
123
+
If you are using any CI/CD tools, ensure the version of MarkBind is updated in the CI/CD pipeline as well.
124
+
- 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).
125
+
126
+
---
127
+
128
+
## Method 2: Install MarkBind locally as a dev-dependency in `package.json`
129
+
130
+
<boxtype="info"seamless>
131
+
132
+
This method is recommended if you
133
+
- are creating a documentation site that more than one person will be working on
134
+
- want to specify the version of MarkBind to use in your project and manage it via `package.json`
135
+
</box>
66
136
67
137
++**1. Initialize a `package.json` file**++
68
138
69
-
:glyphicon-hand-right: _If you already have a `package.json` file, skip to the next step._
139
+
:glyphicon-hand-right: _If you already have a `package.json` file, skip to step 2._
140
+
141
+
: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._
70
142
71
143
To initialize a npm project in your current working directory, run the following command.
72
144
73
145
```
74
-
$ npm init
146
+
npm init
75
147
```
76
148
You will need to answer the prompts to create a `package.json` file.
77
149
@@ -80,7 +152,7 @@ You will need to answer the prompts to create a `package.json` file.
80
152
To get a default `package.json` file, run the following command.
81
153
82
154
```
83
-
$ npm init -y
155
+
npm init -y
84
156
```
85
157
86
158
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.
90
162
++**2. Install markbind-cli locally as a dev-dependency**++
91
163
92
164
```
93
-
$ npm install markbind-cli --save-dev
165
+
npm install markbind-cli --save-dev
94
166
```
95
167
96
168
++**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
115
187
If you are using Git to version control your source files, view the [_User Guide: .gitignore File_](gitignoreFile.html) section for more info.
++**2. Initialize a new Project (or Start with an existing Project)**++
194
+
After you have installed MarkBind, you may want to update to the latest version of MarkBind in the future.
123
195
124
-
<tabs>
125
-
<tabheader="Initializing a new project">
196
+
Go to your project directory that contains the `package.json` file and run the following command.
126
197
127
-
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`.
198
+
```
199
+
npm install markbind-cli@latest --save-dev
200
+
```
201
+
202
+
To update to a specific version of MarkBind, replace `latest` with the version number e.g., `5.0.2`.
128
203
129
204
```
130
-
$ markbind init
205
+
npm install markbind-cli@5.0.2 --save-dev
131
206
```
132
207
133
-
<includesrc="tip.md"boilerplate >
134
-
<spanid="tip_body">
135
-
You can add the `--help` flag to any command to show the help screen. <br>
136
-
e.g., `markbind init --help`
137
-
</span>
138
-
</include>
139
-
<includesrc="tip.md"boilerplate >
140
-
<spanid="tip_body">
141
-
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.
142
-
</span>
143
-
</include>
208
+
If you are using any CI/CD tools, ensure the version of MarkBind is updated in the CI/CD pipeline as well.
209
+
- 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).
144
210
145
-
</tab>
146
-
<tabheader="Starting with an existing project">
211
+
The command will modify your `package.json` and `package-lock.json` file to update the version of MarkBind.
147
212
148
-
Navigate to the project {{ tooltip_root_directory }}.
213
+
---
149
214
150
-
</tab>
151
-
</tabs>
215
+
## Method 3: Install MarkBind via npx
152
216
153
-
++**3. Preview the site**++
217
+
<boxtype="info"seamless>
154
218
155
-
Run the following command in the same directory. It will generate a website from your source files, start a web server, and open a <triggertrigger="click"for="modal:quickStart-livePreview">live preview</trigger> of your site in your default Browser.
219
+
This method is recommended if you want to try out MarkBind without installing it (by using <tooltipcontent="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>).
0 commit comments