MarkBind CLI

Overview

An overview of MarkBind's Command Line Interface (CLI) can be referenced with markbind --help:

$ markbind --help
Usage: markbind <command>
 
 Options:
   -V, --version                                      output the version number
   -h, --help                                         output usage information
 
 Commands:
   init|i [options] [root]                            init a markbind website project
   serve|s [options] [root]                           build then serve a website from a directory
   build|b [options] [root] [output]                  build a website
   archive|ar <versionName> [options]                 archive the current version of the site
   deploy|d [options]                                 deploy the site to the repo's GitHub pages

init Command


Format: markbind init [options] [root]

Alias: markbind i

Description: Initializes a directory into a MarkBind site by creating a skeleton structure for the website which includes a index.md and a site.json.

Arguments:

  • [root]
    Root directory. Default is the current directory.
    Example ./myWebsite

Options

  • -c, --convert
    Convert an existing GitHub wiki or docs folder into a MarkBind website. See Converting an existing GitHub project for more information.

  • -t, --template
    When initialising MarkBind, change the template that you start with. See templates.

Examples

  • markbind init : Initializes the site in the current working directory.
  • markbind init ./myWebsite : Initializes the site in ./myWebsite directory.
  • markbind init --convert --template minimal: Converts the GitHub wiki or docs folder in the current working directory into a minimal MarkBind website.

serve Command


Format: markbind serve [options] [root]

Alias: markbind s

Description: Does the following steps:

  1. Builds the site and puts the generated files in a directory named _site.
  2. Starts a web server instance locally and makes the site available at http://127.0.0.1:8080.
  3. Opens a live preview of the website.

Arguments:

  • [root]
    Root directory. The default is the directory where this command was executed.
    Example ./myWebsite

Options

  • -o <file>, --one-page <file>
    Serves only a single page from your website initially. If <file> is not specified, it defaults to index.md.
    • Thereafter, when changes to source files have been made, the opened pages will be rebuilt if it was affected.
    • Navigating to a new page will build the new page, if it has not been built before, or there were some changes to source files that affected it before navigating to it.
    • Example --one-page guide/index.md

Caveats

Essentially, this optional feature is very useful when writing content, more so if your build times are starting to slow down!

The caveat is that not building all pages during the initial process, or not rebuilding all affected pages when a file changes, will cause your search results for these pages to be empty or outdated, until you navigate to them to trigger a rebuild.

  • -b, --background-build [BETA]
    If --one-page is specified, this mode enhances the single-page serve by building the pages that are not yet built or marked to be rebuilt in the background.

    You can still edit the pages during the background build. When MarkBind detects changes to the source files, the background build will stop, rebuild the files affected, then resumes the background build with the remaining pages.

  • -s <file>, --site-config <file>
    Specify the site config file (default: site.json)
    Example -s otherSite.json

  • -n, --no-open
    Don't open a live preview in the browser automatically.

  • -f, --force-reload
    Force live reload to process all files in the site, instead of just the relevant files. This option is useful when you are modifying a file that is not a file type monitored by the live preview feature.

  • -p <port>, --port <port>
    Serve the website in the specified port.

  • -v [versionNames...], --versions [versionNames...]
    Specify versions to be served, separated by spaces. If the flag is used without specification, serve no versions. Using this option overrides the versions settings in site.json.

Examples

  • markbind serve
  • markbind serve ./myWebsite
  • markbind serve -p 8888 -s otherSite.json
  • markbind serve -n -v LTS 1.0 : Serve the site without opening a live preview in the browser, and also serve the archived version named "LTS" and "1.0".

build Command


Format: markbind build [options] [root] [output]

Alias: markbind b

Description: Generates the site to the directory named _site in the current directory.

Arguments:

  • [output]
    Put the generated files in the specified directory
    Example ../myOutDir

  • [root] [output]
    Read source files from the [root] directory and put the generated files in the specified [output] directory
    Example ./myWebsite ../myOutDir

Options

  • --baseUrl <base>
    Override the baseUrl property (read from the site.json) with the give <base> value.
    Example --baseUrl staging

  • -s <file>, --site-config <file>
    Specify the site config file (default: site.json)
    Example -s otherSite.json

  • -v [versionNames...], --versions [versionNames...]
    Specify versions to be kept in the generated site, separated by spaces. If the flag is used without specification, keep no versions. Using this option overrides the versions settings in site.json.

Examples

  • markbind build
  • markbind build ./myWebsite ./myOutDir
  • markbind build ./stagingDir --baseUrl staging
  • markbind build -v v2.1.1 : Build the site with the version named 'v2.1.1' in addition to the current version

archive Command


Format: markbind archive <versionName> [options]

Alias: markbind ar <versionName>

Description: Does the following steps:

  1. Builds the current site, ignoring previously archived versions.
  2. Updates or creates a versions.json file to track the newly archived version.
  3. Puts the generated files in the specified archivePath folder (By default, the archive path is "version/")

Arguments:

  • <versionName>
    The name of the version. This is required, and names must be unique; using the same name and archivePath will result in the previous archived files being overwritten.
    Example v1, v1.1.1, sem1-2022

Options

  • -s <file>, --site-config <file>
    Specify the site config file (default: site.json)
    Example -s otherSite.json
  • -ap <archivePath>, --archive-path <archivePath>
    All archived versions are stored in the folder <archivePath>. If not specified, the archive path is version/${versionName}
    Example -ap custom_archive_path

Warning: If the folder at <archivePath> already exists, the contents will be overwritten and your previous files may be lost. Only do so if you need to replace all the archived files with the current site files.

(Also note that you cannot save a version with the same name into a different archive path.)

Examples

  • markbind archive v1: Stores the archived site in the directory ./version/v1 as the version named 'v1'
  • markbind archive version_1 -ap custom_archive_path: Stores the archived site in the directory ./custom_archive_path, and the version is named 'version_1'.

Related: User Guide: Site Versioning.

deploy Command


Format: markbind deploy [options]

Alias: markbind d

Description: Deploys the site to the repo's GitHub pages by pushing everything in the generated site (default dir: _site) to the gh-pages branch of the current git working directory's remote repo.

Options

  • -c <githubTokenName>, --ci <githubTokenName>
    Deploy the site in CI Environments using the GitHub personal access token stored in <githubTokenName>. (default: GITHUB_TOKEN)
    Example -c PA_TOKEN

Related: User Guide: Deploying the Website.

--help Option


Format: markbind [command] --help

Alias: markbind [command] -h

Description: Prints a summary of MarkBind commands or a detailed usage guide for the given command.

Examples

  • markbind --help : Prints a summary of MarkBind commands.
  • markbind serve --help : Prints a detailed usage guide for the serve command.