Getting Started

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

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.

Method 1: Install MarkBind globally with npm

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)

    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

    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.

    Starting with an existing project

    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

    1. Update the content of your site. More info can be found in the User Guide: Authoring Contents section
    2. Deploy your site. More info can be found in the User Guide: Deploying the Site 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.

    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

    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).

    • Alternatively, you can use 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

    1. Update the content of your site. More info can be found in the User Guide: Authoring Contents section
    2. Deploy your site. More info can be found in the User Guide: Deploying the Site 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.

    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.

    • For example, update your GitHub Actions workflow file to use the correct version of MarkBind, if you are using markbind-action.

    The command will modify your package.json and package-lock.json file to update the version of MarkBind.

    Method 3: Install MarkBind via npx

    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

    1. Update the content of your site. More info can be found in the User Guide: Authoring Contents section
    2. Deploy your site. More info can be found in the User Guide: Deploying the Site section.

    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

    Authoring Contents