A GitHub Action that builds and deploys your MarkBind site.

• See markbind-reusable-workflows for more details on a list of utilities that can be used to improve your CI/CD with a MarkBind site.

Currently two types of tokens are supported (correspond to the two supported publishing services):

• Token for GitHub Pages
  • Simply use ${{ secrets.GITHUB_TOKEN }}
  • Note that you need to ensure that you have selected the branch that you want to deploy to in your GitHub repo's Pages settings
  • Deployment to GitHub Pages might take 5-10 minutes before the site is available/refreshed
• Token for Surge.sh
  • ${{ secrets.SURGE_TOKEN }}
    • SURGE_TOKEN is the environment secret name
  • Require registration with an email address
  • After retrieving the token, put the token as a repository secret in your repository
  • See here for a detailed guide on how to retrieve the token

Currently two types of publishing services are supported:

• GitHub Pages
  • 'gh-pages'
  • See here for more details
• Surge.sh
  • 'surge'
  • See here for more details

The purpose of the deployment. This can either be standard deployment or for PR preview.

• Standard deployment
  • 'deployment'
  • This is the default value
• PR preview
  • 'pr-preview'
  • This is used if you want to build and preview the updated site whenever there is a PR made to the repository
  • The service must be 'surge' and the domain must be specified
  • Note that this does not work for PR from a fork (due to security reasons)
  • This action will not automatically cleanup merged PR deployments. Follow this instruction to manually tear down the deployed site if required

The domain that the site is available at. Required if service chosen is Surge.

• A surge.sh subdomain
  • '<subDomain>.surge.sh'
  • Surge allows you to specify a subdomain for free as long as it has not been taken up by others. You have to ensure that the <subDomain> is unique.
  • A possible subdomain to use is your repository name: e.g. mb-test.surge.sh
• A custom domain that you have configured with Surge
  • Read the Surge documentation to understand how to set it up
• Additional notes
  • for PR preview purposes, the domain you specify will automatically be prefixed with 'pr-x-', where 'x' is the GitHub event number
    • E.g. 'pr-x-<domain>' (and hence 'pr-1-mb-test.surge.sh')
  • Custom domain does not work with PR preview
  • This action will not automatically cleanup merged PR deployments. Follow this instruction to manually tear down the deployed site if required

The MarkBind version to use to build the site.

• Latest
  • 'latest'
  • This is the latest published version of MarkBind
• Development
  • 'development'
  • This is the latest, possibly unpublished version of MarkBind in development
• Any valid version
  • 'X.Y.Z'
  • This is the version of MarkBind with the specified version number
  • E.g. '3.1.1'
• Any valid version range
  • Internally the action calls npm install to install the specified version of MarkBind
  • Hence, a version range such as '>=3.0.0' (or semantic versioning like '^3.1.1') is also valid

Whether to keep the files in the published branch before pushing. This is a boolean parameter.

• Don't keep
  • false
  • This is the default value
• Keep
  • true
  • This will preserve any existing files in the published branch before an update is made.

The directory to read source files from.

• Root
  • '.'
  • This is the default value
  • This is for the case that your source files of the MarkBind site are in the root directory of the repository
• Any subdirectory
  • './path/to/directory'
  • This is for the case that your source files of the MarkBind site are in a subdirectory of the repository
    • E.g. './docs'

The base URL relative to your domain.

• Default
  • The value of baseUrl in the site config file (typically site.json)
• Any valid base URL
  • For GitHub Pages, you will need to specify this here or in the site config file, in order to configure the relative URL correctly.
    • e.g. '/repoName'
  • For Surge, you will need to ensure that it's specfied as '' here or in the site config file.

The site config file to use.

• Default site config file
  • 'site.json'
  • This is the default value
• Name of your site config file
  • If your site config file is not named site.json, specify the name here
    • E.g. 'ug-site.json'

In essence, there are two parts to a GitHub Action workflow:

• The trigger event
• The jobs/steps to be run after the trigger event occurs

For our context, there are two typical trigger events. This is written at the start of a workflow file: (Assuming 'master' is the target branch)

1. Trigger the action whenever there is a push to the repository

on:
  push:
    branches:
      - master

2. Trigger the action whenever there is a pull request to the repository

on:
  pull_request:
    branches:
      - master

Then, specify a step to use this action:

E.g.

name: MarkBind Action

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 }}
          baseUrl: '/mb-test'
          version: '4.0.0'

The above script builds the site from the repository's root directory, with baseUrl of '/mb-test' ('mb-test' is the repository name), with MarkBind version 4.0.0.

Then, it will deploy the site to GitHub Pages. It runs everytime there is a push to the repository's master branch.

name: MarkBind Action

on:
  push:
    branches:
      - main

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

For GitHub Pages, you will need to specify the baseUrl either as an input in the workflow file or in the site config file(site.json), in order to configure the relative URL correctly.

• baseUrl is typically '/repoName'

name: MarkBind Action

on:
  push:
    branches:
      - main

jobs: 
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Build & Deploy MarkBind site
        uses: MarkBind/markbind-action@v2
        with:
          token: ${{ secrets.SURGE_TOKEN }}
          service: 'surge'
          domain: 'mb-test.surge.sh'

name: MarkBind Action

on:
  push:
    branches:
      - main

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

name: MarkBind Action

on:
  push:
    branches:
      - main

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

name: MarkBind Action

on:
  pull_request:
    branches:
      - main

jobs: 
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Build & Deploy MarkBind site
        uses: MarkBind/markbind-action@v2
        with:
          token: ${{ secrets.SURGE_TOKEN }}
          service: 'surge'
          purpose: 'pr-preview'
          domain: 'mb-test.surge.sh'

Besides processing a few bash scripts, this action utilises the following actions:

• actions/checkout
• actions/setup-node
• peter-evans/find-comment
• peter-evans/create-or-update-comment
• peaceiris/actions-gh-pages