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:

Supported Static Sites

• Application Preview (Create React App, Vite, etc.)
• Documentation Sites (Docusaurus, VitePress, Sphinx, etc.)
• API Docs (Swagger, ReDoc, etc.)
• Code Docs (Javadoc, pydoc, pdoc, etc.)
• ...and any other static docs websites!

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.

   .github/workflows/docs.yaml

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

   .stoat/config.yaml

   ---
   version: 1
   enabled: true
   plugins:
     static_hosting:
       docusaurus:
         metadata:
           # 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:

Framework	Path
Create React App	build
Docusaurus	build
Swagger	dist
Vite	dist
VitePress	.vitepress/dist