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
- Customize a site changes the logo, footer, navigation, and page-agent menu.
- The configuration reference lists every key in
mizzen.yml. - Migrate from 0.2 moves an existing Jekyll-based site to the engine.