• HOME
  • USER GUIDE
  • SHOWCASE
  • ABOUT
  • 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

    Examples

    • markbind init : Initializes the site in the current working directory.
    • markbind init ./myWebsite : Initializes the site in ./myWebsite directory.
    • markbind init --convert : Converts the Github wiki or docs folder in the current working directory into a 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.

    Live preview is:

    • Regeneration of affected content upon any change to .md, .mbd, .mbdf, .njk files ... anything your content depends on!source files, then reloading the updated site in the Browser.

    • Copying files that don't affect page generation (eg. images), but are used in the siteassets to the site output folder.

    Use the serve command to launch a live preview.

    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/mbd.
      • Thereafter, when changes to source files have been made, only the page being viewed 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

    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.

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

    • -t <githubTokenName>, --travis <githubTokenName>
      Deploy the site in Travis CI using the GitHub personal access token stored in <githubTokenName>. (default: GITHUB_TOKEN)
      Example -t 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.