Export static site #

Your design system documentation can be exported using the CLI doc export command. Here we provide common setups that make use of that command to deploy a new version of the documentation static site when new version of the design system is released.

GitHub Actions starter #

It's common to make documentation publishing part of the project CD. We're going to use GitHub Actions to showcase how this can be done.

In the example below, we're going to export the documentation static site into the docs-build dir. The last step, which publishes docs-build content to the site hosting, depends on your stack. We provide integration examples below for some common services.

We are using a new version tag as a trigger for the workflow, but you can use anything else which suits your needs.

Pro tip: set up Git integration and Backlight will push new tag automatically when new version is released.

name: Deploy documentation

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Build docs
        shell: bash
        run: npx backlight@latest doc export @my-workspace/ds-name --dir docs-build
        env:
          BACKLIGHT_API_TOKEN: ${{ secrets.BACKLIGHT_API_TOKEN }}
      - name: Publish docs to your hosting
        ...

Netlify integration #

You can set up Netlify's own build:

• Set Build command to npx backlight@latest doc export @my-workspace/ds-name --dir docs-build.
• Set Publish directory to docs-build (same value passed as --dir argument).
• Add BACKLIGHT_API_TOKEN to the environment variables.

Alternatively, you can use your own CD solution via the manual deployment approach. If you use GitHub Actions, there is a nice wrapper which can take the dir docs-build as input and do the remaining job.

    steps:
      ...
      - name: Publish docs to Netlify
        uses: jsmrcaga/action-netlify-deploy@master
        with:
          build_directory: docs-build
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
          NETLIFY_DEPLOY_MESSAGE: 'Prod deploy v${{ github.ref }}'
          NETLIFY_DEPLOY_TO_PROD: true