Skip to main content

Preview Static Sites in PRs

Stoat can help you preview static sites generated as part of your build in a comment on your pull request.

Here's an example of a Stoat comment that links to a Docusaurus site generated by the latest build:

docusaurus comment screenshot

Supported Static Sites

Example Repo

See a real build that generates a Docusaurus site and links to it in a Stoat comment in this pull request.

Adding documentation previews to the Stoat comment

In this tutorial we will show how to add a Docusaurus static preview to the Stoat comment, but the same approach applies for any static HTML documentation produced by your build.

  1. Set up Stoat with our getting started guide.

  2. Make sure the Stoat Action appears after the GitHub workflow step that generates your Docusaurus build output.

    # existing step in your repo that generates a static Docusaurus build
    - name: Build Docusaurus
    run: |
    npm install
    npm run build

    - name: Run Stoat Action
    uses: stoat-dev/stoat-action@v0
    if: always()
  3. Point Stoat at the generated Docusaurus static build by adding a new task that uses the static_hosting plugin:

    version: 1
    enabled: true
    # a name for the Docusaurus task
    name: "Documentation"
    # path to the Docusaurus build
    path: build

    By default, npm run build will generate static Docusaurus pages in the build directory (documentation here). This is the directory to set for the path field in the Stoat config file. If Docusaurus is built in a subdirectory of the Git repository or if you're using a different docs tool, the path will be different.

  4. That's it! Now, every time you open a pull request, Stoat will host the Docusaurus build and post a comment with a link to the preview. See an example in this pull request.

Default path for Common Frameworks

The Stoat config is similar for all static site generators. The only difference is the path field, which should point to the directory containing the static site files. Here is a table of the default path field for common frameworks:

Create React Appbuild