Documentation from a docs/ folder

1 minute read

You can host a Slipway site alongside your code by making docs/ the site root. The Markdown lives next to the code it documents, and the site is built by the engine, not by GitHub Pages' Jekyll build.

Configure the site

Put mizzen.yml inside docs/ and name the folder in the repository object:

title: My docs
repository:
  url: https://github.com/example/my-project
  branch: main
  dir: docs

repository.dir tells the engine that the site root is docs/ inside the repository. Edit links, the "Use with an agent" prompt, sourcemap.json, and the doctor all name paths such as docs/guide/install.md from the repository root. source defaults to ., so the Markdown in docs/ is the site.

Publish with GitHub Actions

  1. In the repository, open Settings → Pages and set the source to GitHub Actions. Classic branch deployment runs Jekyll and cannot build a Slipway site.
  2. Add a workflow that builds the docs/ folder:
- uses: arminazimi/slipway/action/deploy@main
  with:
    path: docs

The Action installs Node, builds the site, and publishes the output.

Verify in CI

Run the doctor on the same folder, so a missing title or a broken link fails the pull request:

name: Docs

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Slipway Doctor
        uses: arminazimi/slipway/action/doctor@main
        with:
          path: docs
View Markdown

Use with an agent
View Markdown

Open in