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

Examples

  • markbind serve
  • markbind serve ./myWebsite
  • markbind serve -p 8888 -s otherSite.json

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

Examples

  • markbind build
  • markbind build ./myWebsite ./myOutDir
  • markbind build ./stagingDir --baseUrl staging

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.