Skip to content

Documentation Guide

This guide explains how the Shipyard documentation site is structured, authored, and built. Shipyard is the Naftiko Fleet's documentation hub — and this site is Shipyard. It's generated by Zensical from the Markdown files in this repository's docs/ folder.

Source layout

shipyard-docs/
├── zensical.toml          # site config and navigation
├── docs/
│   ├── index.md
│   ├── getting-started/
│   ├── concepts/
│   ├── tutorials/
│   ├── fleet/
│   │   ├── index.md
│   │   ├── editions.md
│   │   ├── getting-started/
│   │   ├── ikanos/
│   │   ├── polychro/
│   │   ├── crafter/
│   │   ├── warden/
│   │   ├── skipper/
│   │   └── shipyard/
│   ├── contributing/
└── overrides/             # custom templates

Each top-level section corresponds to a tab in the site navigation. Components live directly under fleet/ and share a uniform sub-tree (purpose, features, roadmap, faq, releases, license).

Authoring conventions

File naming

  • All files are kebab-case Markdown (my-page.md)
  • index.md is the section landing page
  • File names match the visible page title in slugified form

Front matter

Optional — Zensical reads top-of-file YAML if present:

---
title: "Page Title"
description: "Short description used for SEO and link previews."
---

Headings

  • One # Title per file (matches title: in front matter, if present)
  • Use ## Section, ### Subsection for hierarchy
  • Don't skip levels (don't jump from ## to ####)

Admonitions

Use Zensical-compatible admonition syntax:

!!! tip "Tip title"
    Helpful tip body.

!!! warning "Watch out"
    Warning body.

!!! info "Coming soon"
    Used on draft pages for planned components.

Tabbed content

=== "macOS / Linux"
    ```bash
    polychro lint .
    ```

=== "Windows (PowerShell)"
    ```powershell
    polychro lint .
    ```

Code blocks

  • Always declare the language (```yaml, ```bash, ```java, …)
  • Wrap long lines for readability over horizontal scrolling
  • Reflect the current schema version in YAML samples (currently 1.0.0-alpha3)

Cross-references

  • Use relative paths between files
  • From docs/concepts/x.md to docs/fleet/ikanos/y.md: [Y page](../fleet/ikanos/y.md)
  • From docs/fleet/ikanos/y.md to docs/fleet/ikanos/schema/z.md: [Z page](schema/z.md)
  • Don't link to .html — Zensical handles that during build

Tables over prose

When listing options, fields, or features, prefer tables. Three reasons:

  1. Scannable for human readers
  2. Stable structure for LLM-assisted maintenance
  3. Diff-friendly in PRs

Building locally

# From shipyard-docs/
zensical serve         # live-reload dev server on http://localhost:8000
zensical build         # produces ./site/

Navigation is defined in zensical.toml under [[nav]]. Add a new page by:

  1. Creating the Markdown file in docs/
  2. Adding an entry under the appropriate section in zensical.toml
  3. Running zensical serve to verify

Hierarchical navigation supports up to three levels (tab → section → page).

Voice and tone

  • Direct and concise — short sentences, active voice
  • Reader-aware — assume technical readers; don't over-explain primitives, do explain Fleet-specific concepts
  • Show, don't just tell — every concept gets a YAML or code example
  • No marketing language — features are described by what they do

Submitting changes

Documentation changes follow the standard contribution flow:

  1. Open an issue describing the change
  2. Open a PR against main
  3. CI runs Polychro against any new YAML samples and validates Markdown
  4. A reviewer merges after approval

See Component Contribution Guide for the broader flow.