Getting Started
Prerequisites
a basic knowledge of Markdown and HTML syntax
a basic knowledge of running CLI commands
a recent version of npm installed
Node.js or higher installed
With Node LTS (v20), the python used has updated to 3.12, and you may get an error. You can solve this issue by installing setuptools or deprecating the versions used.
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.
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 globally. This will make the markbind command available in your terminal.
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.
$ markbind
__ __ _ ____ _ _
| \/ | __ _ _ __ | | __ | __ ) (_) _ __ __| |
| |\/| | / _` | | '__| | |/ / | _ \ | | | '_ \ / _` |
| | | | | (_| | | | | < | |_) | | | | | | | | (_| |
|_| |_| \__,_| |_| |_|\_\ |____/ |_| |_| |_| \__,_|
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. Refer to templates section to learn how to use a different template.
Navigate to the project .
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
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.
package.jsonThis method is recommended if you
package.json1. Initialize a package.json file
If you already have a package.json file, skip to step 2.
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
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
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
3. Add scripts in the package.json file
To make the commands available via npm run, add the following scripts to your package.json.
"scripts": {
"init": "markbind init",
"build": "markbind build",
"serve": "markbind serve",
"deploy": "markbind deploy"
}
You are now ready to run MarkBind commands with npm run xxx (e.g. npm run init for markbind init).
npx to run the commands with npx markbind-cli xxx (e.g. npx markbind-cli init for markbind init).If you are using Git to version control your source files, view the User Guide: .gitignore File section for more info.
4. Next steps
5. Updating your MarkBind version
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.
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.
npm install markbind-cli@5.0.2 --save-dev
If you are using any CI/CD tools, ensure the version of MarkBind is updated in the CI/CD pipeline as well.
The command will modify your package.json and package-lock.json file to update the version of MarkBind.
This method is recommended if you want to try out MarkBind without installing it (by using ).
1. Initialize a MarkBind site
npx markbind-cli init mySite
2. Preview the site
cd mySite
npx markbind-cli serve
3. See usage information
npx markbind-cli --help
4. 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