---
theme: auto
colourScheme: ice
---
# Skryb Quickstart
**Skryb** renders supported Markdown, formatting directives, and YAML diagrams
from a portable HTML file. The canonical source remains inside the file. The browser
runtime renders the document and provides tools for editing, checking, saving, and
printing it.
:::grid { columns=2 }
:::panel { title="What you need" palette=accent-soft }
A modern browser and one HTML file. The default file uses an online-hosted
runtime, keeping the document small. Use **Save for Offline** to embed the
runtime and make the document truly standalone.
:::
:::panel { title="Try this document" palette=accent-soft }
Use the document menu to change the theme. Press **Cmd/Ctrl+Shift+E** to open
the source editor, make a change, and save an updated copy. Choose **Edit** on
the flowchart below to move, add, or edit nodes and connectors.
:::
:::
## Work with coding agents
Start with the [basic document template](https://sparkkz-nz.github.io/skryb/templates/skryb-document-template.html)
or install the [Skryb authoring skill](https://sparkkz-nz.github.io/skryb/docs/quickstart.html#use-skryb-with-coding-agents)
for a supported coding agent. The skill defines the document shell, supported
syntax, diagram schema, layout workflow, and document checks. The resulting
source remains available for direct review and editing.
## Create and open a document
1. [Download the basic document template](https://sparkkz-nz.github.io/skryb/templates/skryb-document-template.html).
It has a title, introductory text, and editable flowchart.
2. Open the downloaded file directly in a browser, including through a local
`file://` URL.
3. Choose **Edit source** in the document menu to replace the template content,
then use **Save As** whenever you want a new document.
4. To start from scratch instead, use the HTML shell in the
[reference](https://sparkkz-nz.github.io/skryb/docs/reference.html#html-document-shell). Put Markdown and diagram
YAML in `template#source`; keep
`main#rendered-document` empty.
Frontmatter controls document-wide style. `theme: auto` follows the viewer's
system setting; `light` and `dark` are fixed choices. Select `classic`, `fire`,
`ice`, `midnight`, or `paper` with `colourScheme`. The document menu can change
either setting and writes the result back to frontmatter when you save.
## Add a flowchart
This YAML flowchart shows a browser submitting an order to an API. Flowchart
edit mode can change node and connector presentation, resize or duplicate nodes,
reconnect edges, and move an optional edge waypoint. The edge inspector can
remove the waypoint. The node inspector can add a draggable callout pointer.
```diagram
type: flowchart
version: 1
id: first-flowchart
caption: "Figure #: A browser submitting an order"
description: A browser sends an authenticated order request to the Orders API.
canvas:
auto: true
grid: 5
nodes:
- id: browser
label: Browser
shape: rounded-rectangle
position: { x: 60, y: 110 }
size: { width: 180, height: 80 }
palette: accent
- id: api
label: Orders API
shape: oval
position: { x: 450, y: 110 }
size: { width: 180, height: 80 }
palette: success
- id: order-note
label: |+
## Order request
**Authenticated** customer call
shape: text
position: { x: 390, y: 20 }
size: { width: 260, height: 70 }
edges:
- source: browser
target: api
sourceAnchor: right
targetAnchor: left
label: POST /orders
route: orthogonal
end: arrow
```
Use the diagram toolbar to zoom, fit, or pan. Panning does not alter stored node,
waypoint, or callout coordinates. A diagram frame initially fits its contents.
Drag its bottom edge to change the visible height, or choose **Zoom to fit** to
restore it. Choose **Edit** to change a flowchart, then **Done** to retain the
changes in the matching diagram fence.
`auto: true` derives the canvas size from the drawn content and updates it after
edits. This avoids unused margins in SVG and PDF output. Set an explicit `width`
and `height` only when a fixed aspect ratio matters.
`grid: 5` snaps dragged and resized geometry to multiples of five. This keeps
nodes and connector anchors aligned while allowing small adjustments. Omit the
grid or set it to `0` to disable snapping.
The `caption` appears below the diagram. A `#` placeholder becomes the figure
number, so `"Figure #: ..."` follows the diagram's position in the document.
### Let Skryb place the nodes
The first diagram specifies each node position. For automatic layout, add
`layout: right`, `down`, `left`, or `up`, then omit the positions and connector
anchors that the runtime should derive:
```yaml
type: flowchart
layout: right
canvas: auto
nodes:
- id: browser
label: Browser
shape: rounded-rectangle
- id: api
label: Orders API
shape: oval
edges:
- source: browser
target: api
```
When the document opens, automatic layout fills in only missing geometry.
Existing positions and anchors remain unchanged. Keep `layout` in the baked
source so the runtime can place later additions that omit geometry.
Without `layout`, every node requires a `position` and every edge requires both
anchors. Use that form for manually arranged diagrams that should reject missing
geometry.
Baking writes generated positions and anchors into `template#source` in the
loaded page and marks the document as changed. It does not overwrite the file on
disk. Save the document to persist the baked source. A diagram fence is rewritten
only when it needs layout or requests relayout; comments inside a rewritten fence
are not preserved.
The runtime also checks the document. **Check document** runs the checks again.
Schema failures and edges that reference unknown nodes are errors. Warnings
report overlapping nodes, edges that cross unrelated nodes, overlapping edge
labels, labels that overflow their shapes, and unbalanced aspect ratios. Review
each warning and either correct it or confirm that the geometry is intentional.
Connectors use obstacle routing where possible, and node labels wrap within their
shapes. Long edge labels may still need explicit line breaks at phrase boundaries
to avoid overlaps.
Use the default `orthogonal` route for most connectors. Change anchors first
when a path is unclear. Use `curved` for a long back-edge, several edges sharing
an anchor, or a route that would otherwise overlap another connector or node.
Add a waypoint only when the default route remains ambiguous.
Use the **text** shape for diagram annotations. Its label supports multiple
lines, `# Heading`, `## Subheading`, `**bold**`, _italic_, and ``code``. A text
shape has no fill or border by default. Apply a palette to add them, or select
**None** to remove them. See the [reference](https://sparkkz-nz.github.io/skryb/docs/reference.html#the-text-shape-and-its-markdown-subset)
for the complete text-node syntax.
## Write a longer document
Add `:::toc { depth=2 diagrams=true }` near the top to create a contents list
from headings and captioned diagrams. This directive has no closing `:::`.
Omit `diagrams=true` to list only headings.
Give a diagram an `id` and a `caption` to reference it from prose:
```markdown
See Figure {ref=first-flowchart} for the order path.
```
This renders as a link. For a numbered caption, the link uses the figure number;
otherwise it uses the caption text. Figure numbers update from document order.
The `id` is also an anchor, so `#first-flowchart` links directly to the diagram.
Add a recognised language to a code fence to enable syntax highlighting:
```typescript
export const total = items.length;
```
Recognised names include `typescript`, `python`, `sql`, `bash`, `json`, `yaml`,
`html`, `css`, and `diff`. An unrecognised name renders as plain code. The
[reference](https://sparkkz-nz.github.io/skryb/docs/reference.html#syntax-highlighting)
lists all recognised names.
When several nodes share presentation, define a named style and apply it with
`class`:
```yaml
styles:
external:
palette: neutral
style: { strokeWidth: 3 }
nodes:
- id: bank
label: Partner bank
shape: rounded-rectangle
class: external
```
Node-level values override the class, allowing individual exceptions without a
second named style.
## Navigate diagrams and references (next runtime release)
The following additions are not yet in published `latest` or an existing pinned
release. This guide currently loads `latest`.
- Click or Tab into a diagram to activate wheel panning and Ctrl/Cmd+wheel zoom.
An outline marks the active diagram. Until activated, the wheel scrolls the
document. Click or move keyboard focus outside to deactivate it.
- Double-click empty diagram background to expand it; repeat to return to the
document. The expand control and Escape remain available. Expansion activates
wheel controls; collapse deactivates them without changing saved coordinates.
- Give a flowchart node `href: "#detail"` to navigate to a diagram ID or heading
in the same document. Use **Destination** in its inspector to edit the link.
Add an ordinary Markdown return link beside the detail view.
- Add `ref: 3`, `ref: Start`, or `ref: { label: 3, position: ne }` to a
flowchart node, connector, or sequence message. One or two digits produce a
circle; other labels produce a stadium. Prose uses `{annotation=3}` for the
same noninteractive badge. Use **Reference** in the element inspector to
change or remove it. These badges do not number themselves or navigate.
See the [node navigation](https://sparkkz-nz.github.io/skryb/docs/reference.html#node-navigation)
and [annotation badge](https://sparkkz-nz.github.io/skryb/docs/reference.html#annotation-badges)
contracts for destination validation and badge placement rules.
## Export a diagram
Each diagram toolbar has an **Export** menu:
- **Open full diagram** opens the diagram alone in a new browser tab.
- **Save as SVG** downloads a standalone, scalable vector image that can be
opened in a browser or compatible graphics application.
- **Save as Skryb diagram** downloads an editable single-diagram document that
can be imported into another document through the source tray.
- **Print / Save as PDF** opens the browser's native print dialog for the
diagram alone.
Exports retain the current theme background and diagram font, but omit editor
controls as well as the current zoom and pan position.
## Edit canonical source
**Edit source**, or Cmd/Ctrl+Shift+E, opens the resizable source tray. Drag its
top edge to change the tray height, or focus that edge and use the arrow keys;
double-click it to restore the default height. It live-renders valid changes,
while preserving the last valid document and showing a precise error for an
invalid draft. Double-click rendered text to open the tray at its matching
source. Double-click and drag a text selection for more search precision.
The tray menu inserts valid templates for a flowchart, sequence, diagram
reference, contents, panel, or grid. Use it for document structure and sequence
participants, message order, activations, and groups. The graphical sequence
inspector edits participant, note, and message presentation. Participants appear
left to right and messages appear top to bottom in source order.
## Save the result
- **Print / Save as PDF** prints the complete document without toolbars.
Diagrams use their natural size, and panels, diagrams, and tables remain
together across page boundaries. **Cmd/Ctrl+P** opens the same print dialog.
- **Save As** downloads an updated portable HTML document and retains its hosted
runtime URL.
- **Save for Offline** downloads one self-contained HTML document with the
selected runtime embedded. When the document uses a hosted runtime, the
browser fetches it during export, so this step requires network access.
The [reference](https://sparkkz-nz.github.io/skryb/docs/reference.html#saving-printing-and-offline-use)
describes the uncommon fully local authoring workflow.
- **Cmd/Ctrl+S** downloads the latest valid source. **Cmd/Ctrl+Shift+E** opens or
closes the source tray.
## Keep going
- Read the [Skryb reference](https://sparkkz-nz.github.io/skryb/docs/reference.html) for the supported document,
formatting, flowchart, and sequence fields.
## Use Skryb with coding agents
Install the schema-aware `skryb-document` skill to make this authoring contract
available to every supported local agent:
```sh
npx skills add sparkkz-nz/skryb --skill skryb-document --agent '*' --global --yes --full-depth
```
Omit `--global` for a project-only install. Run `npx skills update --global` to
receive the latest version. The [skill source](https://github.com/sparkkz-nz/skryb/tree/main/.github/skills/skryb-document)
is versioned alongside Skryb.