slipway-content
Write or edit a page on a Slipway site, or translate one into another language, using the engine's front matter keys and directives, then check it with slipway check.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 2
- Forks
- 2
01 前言 Front Matter
- name
- slipway-content
- metadata
- { "version": "0.3.0" }
- description
- Write or edit a page on a Slipway site, or translate one into another language, using the engine's front matter keys and directives, then check it with slipway check.
02 资源文件 5
- 参考文档examples/doc-page.md575 B
- 参考文档examples/post-fa.md902 B
- 参考文档examples/post.md580 B
- 参考文档reference/front-matter.md3.1 KB
- 参考文档reference/translate-page.md2.1 KB
03 SKILL.md 正文
Write pages on a Slipway site
A Slipway site is a folder of Markdown files, each with an optional block of front matter. The engine builds every .md and .html file under the site's source folder into a page; the theme renders the title, the navigation, the table of contents, and the language switcher. You write the front matter and the words. If the site has an AGENTS.md, read it first; it wins where it differs from this Skill.
1. Take a baseline
Run the check once, before you change anything, and keep its output:
slipway check .
Run it from the site folder. Your edit is done when it adds no finding that names your file.
slipway is the engine's command line. It is released with the engine (engine.cli). Until it is installed, no check can run: say so in your report and do not invent a result.
2. Pick the file and its URL
| You are writing | File | URL |
|---|---|---|
| A page | any .md file under the source folder, such as guide/install.md |
the path: /guide/install/ |
| A folder's index | index.md, or README.md when the folder has no index.md |
the folder: /guide/ |
| A page in another language | a file under that language's prefix folder, such as fa/install.md |
the prefix and the path: /fa/install/ |
| A page that moves or has a custom address | any file, with permalink |
the permalink value |
Folders whose names start with . or _ are skipped, unless slipway.yml lists them under include. Files in node_modules, the output folder, and slipway.yml are never pages.
Do not rename or move a published page to change its title. Set title. A page's address is its path or its permalink, and links to it would break if you change it. To change an address on purpose, set permalink and add a redirect_from entry for the old one.
Set published: false to keep a draft out of the build. Do not create _posts/ folders: posts are not part of the engine.
3. Fill the front matter
Every key the engine reads, its type, and its allowed values are in reference/front-matter.md. Use only keys it lists.
titleis the page heading. Without it, the firsth1is used.description: one sentence for the meta description,llms.txt, and search.order: a number that sorts the page among its siblings in navigation built from folders.layoutis usually left out. The folder'sdefaultsinslipway.ymlor the theme's default layout applies. Set it only when the theme documents the layout name.permalinkstarts with/. Leave it out unless the address must differ from the path.redirect_fromlists old addresses (a string or a list) that now redirect to this page.statusis one ofexperimental,beta,deprecated,proposed,accepted,rejected, orsuperseded.agenttells agents how to edit the page:edit: falsefor a generated page,sourcefor the file to edit instead, andnotesfor one short instruction.- Quote a value that contains
:or starts with a character YAML treats specially ([,{,*,&,!,#,|,>,@, or a backtick).
Two keys are deprecated aliases: nav_order is order, and direction is dir. Do not write them in new content; the engine warns about them.
4. Write the body
- Plain Markdown. The title is the page heading, so start sections at
##and never add a second#heading. - Keep heading levels in order (
##, then###), so the table of contents finds every section. - Link to a page by its URL path, such as
[Install](/docs/install/). Check the link withslipway check. - Give each image alt text:
. - Give every code block a language (
```yaml), so it highlights and reads left to right on a right-to-left page.
Directives
The engine turns these into theme components. A name the theme does not ship renders as an unknown-component warning, so use only the names below.
| Write | Component | Options |
|---|---|---|
:::callout{type=tip} … ::: |
callout |
type: note (default), tip, important, warning, caution. title="…" replaces the default heading. |
> [!WARNING] followed by a quote |
callout |
GitHub alert: NOTE, TIP, IMPORTANT, WARNING, CAUTION. |
:::details{summary="…"} … ::: |
details |
summary is the visible label. Add open to start expanded. |
:::steps … ::: |
steps |
The body is one ordered list. |
:::file-tree{label="…"} … ::: |
file-tree |
The body is a nested list. A name ending in / is a folder; text after # is a note on that row; **name** highlights it. |
:badge[New]{variant=tip} |
badge |
Inline. variant: note (default), tip, important, warning, caution. |
::badge{label=new} |
badge |
Block form, with label as the text. |
Example, from examples/doc-page.md:
:::callout{type=tip}
The binary has no dependencies. Copying it to another machine is enough.
:::
Use a callout for a note the reader must not miss, not for decoration.
examples/doc-page.md is a template for a doc page: its first comment says where the file goes.
5. Add a translation
- The language must be in
languagesinslipway.yml, with acode, aname, and aprefixsuch as/fa. If it is missing, ask the owner before you add it: it changes every page's language switcher. - Give the original page a
translation_key(such asinstall) if it has none, and alangif it does not inherit one from its folder. The switcher links a page and its translations bytranslation_key. - Give the translation the same
translation_key, andlangset to its language code. Its URL comes from its path under the prefix folder:fa/install.mdbecomes/fa/install/. - Translate
title,description, and the body. Keep thetranslation_key, the code, the commands, the file names, and the URLs as they are. - Do not set
diron a translation. The direction comes fromlang:fa,ar,he, andurare right to left. - In Persian text, use Persian
یandک(not the Arabicيandك), a zero-width non-joiner in words such asمیشود, and Persian punctuation (،and؟). Put commands, file names, and code in backticks: they stay left to right inside the sentence.
Change translation_key on every page that shares it, or on none. Changing it on one translation only breaks the link.
6. Check the edit
From the site folder:
slipway check .
Each finding is printed with its file and line. Fix it at that line and run the check again. To get a machine-readable report, add --format json or --format sarif.
Build the site before you finish a change to navigation, languages, or directives:
slipway build . --out dist
Read every error and warning and fix it at the file it names. Then compare the result with your baseline: a finding that names your file is yours to fix.
Never
- Never invent a front matter key that reference/front-matter.md does not list.
- Never write a second
#heading in the body. - Never edit the output folder (
dist/or the folder you passed to--out); the build replaces it. - Never create
_posts/pages. Posts are not part of the engine. - Never rename or move a published page to change its title; set
title. - Never change
translation_keyon one translation only. - Never change theme layouts or components to change how one page looks.
04 同仓库更多 Skills
slipway-translate
Add a language to a Slipway site, translate pages, and keep every translation linked through lang and translation_key, then check it with slipway check.
slipway-site
Create a Slipway docs site, or customize an existing one through slipway.yml, navigation, languages, redirects, and theme options, then check it with slipway check.
slipway-release-notes
Write a changelog entry and a release page from merged pull requests, for a site built with Slipway or for Slipway itself.
slipway-doctor
Check a static site with slipway doctor after you edit it, read the findings, and fix them until the site reaches its conformance level. Use for any Slipway site or any site that follows the agent-editable site spec.
slipway-design
Restyle a Slipway site with design tokens and a preset, add CSS through the override slots, and keep light and dark contrast passing.
slipway-deploy
Publish a Slipway site to GitHub Pages with the deploy Action, set a custom domain, and fix the common build, base path, theme, and permission failures.