Deploying the Site

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.

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

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.

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

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

Adding your repository to Travis CI

Add your repository on travis-ci.com

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.

---

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

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

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

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