Deploying the Site

User Guide → Deploying the Site

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.

Using the markbind deploy command

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:

User Guide: Configuring the Site → deploy



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.

Using CI Platforms

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

Generating a Github Personal Access Token

With the exception of Github Actions, a Github Personal Access Token with repo permissions is required for deploying your MarkBind site to Github Pages via CI tools.

You may refer to Github's documentation on how to generate a Github Personal Access Token. Ensure that you have enabled repo permissions as shown from the screenshot below.

Take note of the generated token - you will not be able to see it again once you navigate away from the page.

Deploying via Github Actions

To instruct Github Actions to build and deploy the site when you push to the repository, add a Github Actions workflow file in your project repo at the location <PROJECT_ROOT>/.github/workflows/deploy.yml A sample workflow file is provided below:

name: Deploy Markbind Site
on:
  push:
    branches: master

jobs:
  build:
    runs-on: ubuntu-latest
    name: test
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '10'
      - run: npm i -g markbind-cli
      - run: markbind build
      - run: markbind deploy --ci

The sample deploy.yml workflow above uses the default Github Token secret that is generated automatically for each Github Actions workflow. You may also use a Github Personal Access Token in place of the default Github Token.

Once you have created the file, commit and push the file to your repo. Github Actions should start to build and deploy your markbind site. You can verify this by visiting www.github.com/<org|username>/<repo>/actions.

For more information on customizing your workflow file to fit your specific needs, you may refer to the Github Action Docs.


Deploying via Travis CI

Adding your repository to Travis CI

Travis CI Migration

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.

Configuring your repository in Travis CI

  1. Add an environment variable in Travis CI named GITHUB_TOKEN, with the value set to your generated Github Personal Access Token. Ensure that Display value in the build log is set to Off.

  2. 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:
      - 10
    install:
      - npm i -g markbind-cli
    script: markbind build
    deploy:
      provider: script
      script: markbind deploy --ci
      skip_cleanup: true
      on:
        branch: master
    

More information about .travis.yml can be found in the Travis CI documentation.

  1. Commit .travis.yml to your MarkBind repository and push the changes. Travis CI should begin to build your site.
  2. Select the MarkBind repository on Travis CI and check the build status to see if it is successful.
  3. 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 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 add to the deploy phase a repo condition in the form owner_name/repo_name.

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

  on:
    branch: master
    repo: se-edu/se-book

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


Deploying via AppVeyor CI

Adding your repository to AppVeyor CI

  1. Sign in to AppVeyor CI using your Github Account.

  2. Authorize AppVeyor App as Github App in the account settings by clicking on the Install AppVeyor App button.

  3. In the projects directory, click on the New Project button.

  4. Finally, select the repository containing your Markbind site.

Configuring your repository in AppVeyor CI

  1. Ensure that you have generated a Github Personal Access token with repo permissions.

  2. Navigate to the project settings page of your repository in AppVeyor CI.

  3. On the left menu, click on Environment.

  4. Under the heading Environment variables, add a custom environment variable named GITHUB_TOKEN, with the value set to the personal access token that was generated in the first step. Ensure that you toggle variable encryption by clicking on the padlock.

  5. Remember to click Save at the bottom of the page.

  6. Add a appveyor.ymlfile at the root of your Markbind site's repository to instruct AppVeyor CI to build and deploy the site to Github Pages when you to push to your repository. More information on customizing appveyor.yml can be found in AppVeyor documentation. An example appveyor.yml file is given below:

    environment:
      nodejs_version: '10'
    
    branches:
      only:
        - master
    
    install:
      - ps: Install-Product node $env:nodejs_version
      - npm i -g markbind-cli
      - markbind build
      - markbind deploy --ci
    
    test: off
    
    build: off
    

Commit and push appveyor.yml to your github repository. Thereafter, AppVeyor CI should begin to run the build script. You are able to view the current build status by clicking on your repository in the AppVeyor projects page. Once the build succeeds, you should be able to view your Markbind site, after a few seconds, at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book.


Deploying via Circle CI

Adding your repository to Circle CI

  1. Ensure that you have generated a Github Personal Access Token with repo permissions.

  2. Sign in to Circle CI using your Github account.

  3. In the projects dashboard, click on the Set Up Project button beside the repo containing your Markbind site.

Configuring your repository in Circle CI

  1. Once you have set up your project, click on the Project Settings button.

  2. On the left, click on the Environment Variables tab and add a custom Environment Variable, GITHUB_TOKEN, which contains the value of your Github Personal Access Token.

  3. Commit and push a config.yml file to the repo containg your Markbind Site that instructs Circle CI to build and deploy your Markbind site to Github Pages whenever you push to your repository. Ensure that the config.yml file is located in the <PROJECT_ROOT>/.circleci/ directory. A sample config.yml file is shown below:

    jobs:
      Build-And-Deploy:
        docker:
          - image: 'cimg/base:stable'
        steps:
          - checkout
          - node/install:
              node-version: "10"
              npm-version: "6"
              install-yarn: false
          - run: node --version
          - run: npm i -g markbind-cli
          - run: markbind build
          - run: markbind deploy --ci
    version: 2.1
    orbs:
      node: circleci/node@4.1.0
    workflows:
      Deploy-Markbind-Site:
        jobs:
          - Build-And-Deploy
    

After you have pushed the config.yml file to your remote repo, you should see Circle CI starting to run the Deploy job in your projects dashboard. Once it is successful, you should be able to view your Markbind site at http://<username|org>.github.io/<repo>.

For more information on customizing your build script, you may refer to Circle CI Config Reference Document.



Deploying to Netlify

You can setup a platform for deploying static webpages (among other things)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
    • Show advanced: Add a new variable with the key as NODE_VERSION and the value as 10 or higher

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.

Previewing Pull Requests for MarkBind sites

If you are hosting your Markbind project on Github, you can setup Pull Request previewsPR previews in order to automatically build and deploy the modified Markbind site based on the changes in the PR.

Previewing PRs using Netlify

By following the steps to deploy to Netlify in the previous section, you would automatically be able to preview PRs.

You can preview the updated site at the bottom of the pull request by clicking on details link in the PR:

For more information on previewing PRs with Netlify, you may refer to Netlify's docs.

Previewing PRs using Surge

You may also preview PRs using Surge, which is an NPM package that does static web publishing. Here are the steps to do so:

  1. First install Surge using by typing npm install --global surge on your terminal.

  2. Next, type surge in the terminal. You should see the following prompt:

  3. Proceed to create a Surge account. After you have set up your account, you should see the following screen:

  4. Hit CTRL-C on your keyboard to quit the current running Surge process.

    The rest of the Surge setup is unnecessary for the purposes of setting up PR previews. You may still proceed with the rest of the setup such as setting the project directory and the domain name, if you wish to.

  5. Next, type surge token to generate your surge token.

  6. In the repo of your markbind site, create a new secret by going to "Settings"->"Secrets" and naming it as SURGE_TOKEN and setting its value to the value of the generated surge token.

  7. Commit and push the following 2 files into your markbind site repo, in the directory <PROJECT_ROOT>/.github/workflows/.

receivePR.yml File


previewPR.yml File


Finally, you may open a PR to the repo of your Markbind site. If everything is configured correctly, after a few minutes, you should be able to see a github-actions bot automatically commenting on the PR with a link to preview the updated Markbind site.

For more information on Surge, you may refer to Surge's docs.

Relevant Tips & Tricks

Configuring Online Deployment platforms to use specific MarkBind version