• HOME
  • USER GUIDE
  • SHOWCASE
  • ABOUT
  • Deploying the Site

    A site generated by MarkBind can be deployed by simply uploading the generated files to any Web server. In addition, MarkBind provides several convenient deployment options.

    Generic steps for deploying a MarkBind site:

    1. Set the baseUrl property of the site.json file to match the deploy location.
    2. (Optional) Use the markbind serve command to stage the site locally and confirm the contents are as expected.
    3. Use the markbind build command to generate the site from source files. That command puts the generated site files in a directory named _site (you can change the output directory using parameters supplied to the command).
    4. Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.

    Steps for deploying multiple MarkBind sites:

    1. Create multiple site.json files. Ensure that the baseUrl property of each site.json file matches its deploy location.
    2. (Optional) Use the markbind serve -s <file> command to stage each site locally and confirm the contents are as expected.
    3. For each site:
      1. Use the markbind build -s <file> command to generate the site from source files.
      2. Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.

    Deploying to Github Pages

    MarkBind can easily deploy a site to Github pages if the project root directory is also a GitHub repo.

    Running the markbind deploy command will deploy the most recent build of your site to the gh-pages branch of the repo origin and will be available After the command is completed, your site will be online at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book.

    If you are deploying to the site to GitHub pages, the baseUrl setting in the site.json should be set to the "/<repositoryName>" for the links in the deployed site to work correctly.
    Example: If you are using Github Pages to host your deployed website at repo myorg/myproduct (i.e., the website is published at https://myorg.github.io/myproduct), then your baseUrl should be "/myproduct".

    You can override the default deployment settings (e.g., repo/branch to deploy) in the site.json's deploy section:

    deploy

    The settings for auto-deployment to Github pages.

    • message [Optional. Default: "Site Update."]
      The commit message used for the deployment commit.

    • repo [Optional. Default: the current working project's repo]
      The repo you want to deploy to.
      Format: "https://github.com/<org|username>/<repo>.git" ("git@github.com:<org|username>/<repo>.git" if you use SSH)
      Example: "https://github.com/myorg/myrepo.git"

    • branch [Optional. Default: "gh-pages"]
      The branch that will be deployed to in the remote repo.


    markbind deploy does not generate the static site from your source; it simply deploys the files that are already in the _site directory. You need to run markbind build first if you want to generate the site before deploying.

    Deploying to GitHub Pages via Travis CI

    You can setup Travis CI to automatically build and deploy your site on GitHub Pages every time your GitHub repo is updated.

    Adding your repository to Travis CI

    Since May 2018, Travis CI has been undergoing migration to travis-ci.com, which changes the way you setup repositories on Travis CI.

    • If you are new to Travis CI, you should add your repository on travis-ci.com.
    • Alternatively, if you are already using Travis CI on travis-ci.org, you can continue to add your repository on travis-ci.org.

    1. Sign in to Travis using your GitHub account.
    2. Accept the authorisation for Travis CI when you are redirected to GitHub.
    3. Go to the Repositories page, and click on the green Activate button.
      If you are already using Travis CI, click on the white Manage Repositories on GitHub button instead.
    4. Select the repository with the MarkBind site, and add the Travis CI GitHub App to the repository by clicking the green Approve and Install button.
    1. Sign in to Travis using your GitHub account.
    2. Accept the authorisation for Travis CI when you are redirected to GitHub.
    3. Go to the Repositories page.
    4. Find the repository with the MarkBind site.
      If the organization/repository is not shown in the list, click on Review and add link at the bottom of the list of organization and follow the steps to give Travis access to the organization containing your repo. After that, come back to the Repositories page and use the Sync Account button to sync your Travis account with GitHub.
    5. Activate the repo using the slider switch in front of it.

    Configuring your repository in Travis CI

    1. Generate a GitHub personal access token with repo permissions. Take note of the generated token - you will not be able to see it again once you navigate away from the page.
    2. Add an environment variable in Travis CI named GITHUB_TOKEN, with the value set to the personal access token generated in the previous step. Ensure that Display value in the build log is set to Off.
    3. Add a .travis.yml file to instruct Travis CI to build and deploy the site when you push to the repository. An example .travis.yml file that can accomplish this is given below:
      language: node_js
      node_js:
        - '8'
      install:
        - npm i -g markbind-cli
      script: markbind build && markbind deploy --travis
      branches:
        only:
        - master
      
      More information about .travis.yml can be found in the Travis CI documentation.
    4. Commit .travis.yml to your MarkBind repository and push the changes. Travis CI should begin to build your site.
    5. Select the MarkBind repository on Travis CI and check the build status to see if it is successful.
    6. Once the build succeeds, your MarkBind site should be online at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book. Travis CI will automatically build and deploy changes to your site as you push new changes to the repository after a few seconds.
      You might have to go to the Settings of your repo and configure it to publish GitHub Pages from the gh-pages branch as MarkBind deploys to that branch by default.
    Configuring Travis CI to use a specific MarkBind version

    When Travis CI is set up as explained above, it will use the latest version of MarkBind which may be a later version than the one you use locally.

    • If you want Travis CI to use a specific version of MarkBind (eg. v1.6.3), change the install step in the .travis.yml given above to:
      install:
        - npm i -g markbind-cli@1.63
      
    • If you want to use the latest minor version automatically until the next major version (as major versions usually contain breaking changes), you can add a ^ in front of the version number. In the example below, Travis will use the latest version of MarkBind but will stop before 2.*
      install:
        - npm i -g markbind-cli@^1.63
      
    Configuring Travis CI to only deploy from a specific repository

    When Travis CI is set up as explained above, Travis CI will attempt to deploy the site from any repository it is in, including forks. If you want Travis CI to only deploy from a specific repository (eg. only from your main site repository), you can set a deploy phase with an on condition.

    For example, if you only want Travis CI to deploy the site when it is run from the se-edu/se-book repository, the folllowing deploy phase with the on condition should be added to .travis.yml:

    deploy:
      on:
        repo: se-edu/se-book
    

    The repo value can be changed to your specific repository as desired.


    Deploying to Netlify

    You can setup Netlify to automatically build and deploy your site on their platform every time your GitHub repo is updated.

    Here are the steps to set up Netlify:

    1. Go to https://app.netlify.com/ and sign up
    2. Next go to https://app.netlify.com/account/sites and select New site from Git
    3. Select your git provider
    4. Select your markbind site repository
    5. Update the build settings as follows and hit Deploy site:
      • Build Command: npm i markbind-cli -g && markbind build --baseUrl
      • Publish directory: _site

    Now your site will be deployed on Netlify at the given address specified after deployment. It will be updated automatically when the default branch of your repo is updated.

    Additionally, when contributors make a pull request to your GitHub repo, you can preview the updated site at the bottom of the pull request by clicking on details link in the PR:

    Note that when Netlify is set up as explained above, it will use the latest version of MarkBind which may be a later version than the one you use locally. If you want Netlify to use a specific version of Netlify, follow the instructions in the box below:

    Setting up Netlify to use a specific version of MarkBind

    Here are the steps to set up Netlify to use a specific version of MarkBind.

    1. Navigate to the root directory of your site.

    2. run npm init which will create package.json and package.lock.json

    3. run npm install markbind-cli@1.6.3 --save to install markbind as a dependency (using v1.6.3 as an example)

    4. create/update .gitignore file in the root directory and add:

      node_modules
      
    5. update ignore in site.json to include

      node_modules/*
      .gitignore
      
    6. Now, follow the previous instructions for setting up Netlify but with the following difference:
      In step 5, Set the Build Command to markbind build --baseUrl

    Making the Site Searchable

    MarkBind in the Project Workflow