Skip to content

gettingStarted.md

Latest commit

 

History

History
291 lines (195 loc) · 9.02 KB

gettingStarted.md

File metadata and controls

291 lines (195 loc) · 9.02 KB

{% set title = "Getting Started" %} {{ title }}

title: "User Guide - {{ title }}" layout: userGuide.md pageNav: 2

{{ title }}

++Prerequisites++

%%{{ icon_ticked }}%% a basic knowledge of Markdown and HTML syntax
%%{{ icon_ticked }}%% a basic knowledge of running CLI commands
%%{{ icon_ticked }}%% a recent version of npm installed
%%{{ icon_ticked }}%% Node.js {{ node_version }} or higher installed

If you already have Node.js ({{ node_version }} or higher) and npm installed, you can skip this section.

Visit the Node.js download page.

  • Option 1: Download a prebuilt installer (Windows/MacOS)
    • This automatically sets up npm.
  • Option 2: Install through the Command Line (any OS)
    1. Select your OS and architecture from the dropdowns on the same page.
    2. Make sure to choose “with npm”.
    3. Run the provided commands in your terminal to install Node.js and npm.

After installation, in your terminal run:

node -v
npm -v

The versions for node and npm should match or exceed the requirements mentioned in the Prerequisites.

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

Navigate into an empty directory and run:

markbind init

This command creates a skeletal MarkBind site in that directory, with files like index.md and site.json.

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.app/). Refer to [templates](templates.html) section to learn how to use a different template. If you use AI coding assistants, you can install project-level skills using `markbind skills install`. See [CLI Commands: `skills`](cliCommands.html#markbind-skills).

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 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 can update to the latest version by running:

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++

: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

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.

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

++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

++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') }}