Install and quickstart

2 minutes read

Slipway is a documentation engine and a theme. The engine, Mizzen, turns Markdown in your repository into a site; the theme, Lateen, renders it. A Slipway site needs Node, not Ruby, and there is no Jekyll build step.

Requirements

  • Node 24 or later.
  • Git, and a GitHub repository when you want the included workflow to publish the site.

Create a site

Run the starter in an empty folder:

npm create slipway@latest my-site

It asks for the folder, a title, the repository, and the language, then writes a working docs site. Agents and scripts can pass every answer as a flag and skip the questions:

npm create slipway@latest my-site --title "My docs" --repository me/my-docs --lang en --yes
Flag Default Meaning
<dir> required Folder for the site. It must be empty or not exist.
--title the folder name Site title.
--repository The GitHub repository as owner/name or an https URL. It sets url and base and adds "Edit this page" links.
--lang en Language code, such as en, fa, or pt-BR.
--yes, -y Never prompt. Without a terminal it never prompts either.

The new site has these files:

mizzen.yml                        the site config
docs/index.md                     the home page
docs/quickstart.md                the first guide
docs/configuration.md             the configuration reference
.github/workflows/deploy.yml      build and publish to GitHub Pages
content-schemas.json              which schema checks which file
schema/                           the config and front matter schemas

Build and preview

From the site folder, install the engine and the theme, then check and build:

npm install --save-dev @velella/mizzen @velella/lateen
npx mizzen check .
npx mizzen build . --out dist

check builds to a temporary folder and prints diagnostics, so it is the command to run before you commit. build writes the site to dist; change the folder with --out. A build fails on an unknown config key, an unknown layout, or two files that write the same path. Installing both packages in package.json also pins the versions for the next person.

To read the result in a browser, serve the output folder rather than opening a file directly:

npx serve dist

Write a page

Every Markdown file under source (set in mizzen.yml) is a page. Add docs/about.md:

---
title: About
description: Who we are.
---

We write documentation.

The page is published at /about/. A title in front matter is optional: without it, the first # heading is the title, and without that the file name is. Links are ordinary Markdown links. Keep them relative to the page's published URL, or absolute:

See [Install and quickstart](../install/) and the [configuration reference](../config/).

Publish to GitHub Pages

The generated workflow builds the site with the deploy Action on every push to main:

- uses: arminazimi/slipway/action/deploy@main
  with:
    path: .

In the repository, open Settings → Pages and set the source to GitHub Actions once. The workflow does the rest: it installs Node and the engine, builds the site, and publishes the output. Classic GitHub Pages, which ran Jekyll, cannot build a Slipway site.

Next steps

View Markdown

Use with an agent
View Markdown

Open in