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

  • Set the baseUrl property of the site.json file to match the deploy location.
  • (Optional) Use the markbind serve command to stage the site locally and confirm the contents are as expected.
  • 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).
  • 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:

  • Create multiple site.json files.
  • (Optional) Use the markbind serve -s <file> command to stage each site locally and confirm the contents are as expected.
  • For each site:
    • Use the markbind build -s <file> command to generate the site from source files.
    • 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.

This documentation currently uses master as the default branch name. If your repository uses main as the default branch, you will need to update the references to master accordingly. For instance, when specifying the branch for deployment, replace instances of master with main to match your repository's configuration.

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.

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 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 generates the static site from your source by default; hence, it is not necessary to run markbind build first to generate the site before deploying. To skip the site generation, you can use the --no-build option for markbind deploy.

More information can be found in the CLI Commands section.

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.

GitHub Token Repo Permissions
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
    permissions:
      contents: write
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm i -g markbind-cli
      - 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.

Then, navigate to the Settings > Pages section on GitHub for that repository and set the source to the root of the gh-pages branch. You can read this source on GitHub Pages for more details.

GitHub Actions should start to build and deploy your MarkBind site. You can verify this by visiting www.github.com/<org|username>/<repo>/actions.

MarkBind provides a helper GitHub Action that you can use to simplify your workflow file. A sample workflow file utilizing the action is as follows:

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

jobs: 
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Build & Deploy MarkBind site
        uses: MarkBind/markbind-action@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

Read the action documentation to understand the various configuration options.

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.

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

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.

    Add GITHUB_TOKEN
  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:
      - 18
    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.

    Install AppVeyor GitHub App
  3. In the projects directory, click on the New Project button.

    Add a new Project on AppVeyor
  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.

    Add GitHub Token on AppVeyor
  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 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: '18'
    
    branches:
      only:
        - master
    
    install:
      - ps: Install-Product node $env:nodejs_version
      - npm i -g markbind-cli
      - 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.

    Set Up Project in Circle CI

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.

    Add GitHub Token in Circle CI
  3. Commit and push a config.yml file to the repo containing 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: "18"
              npm-version: "10"
              install-yarn: false
          - run: node --version
          - run: npm i -g markbind-cli
          - 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 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

    Create a new site
  4. Select your MarkBind site repository

    Select 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 18 or higher

    Update build settings

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

Preview deploy

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:

    Create Surge account
  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.

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

    Add Surge token

    After aquiring the surge token, you may want to utilize the provided MarkBind reusable workflows to conveniently set up your PR preview via Surge.sh.

    If you would like to find out more about how it works behind the scene and how to do it yourself, read on to see the detailed steps that need to be specified in your workflow files.

  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.

Surge PR bot

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

Relevant Tips & Tricks

Configuring Online Deployment platforms to use specific MarkBind version