Writing Examples & Showcases

What makes a good example

Each example in the repository demonstrates one part of the language clearly enough to copy without regret. The bar is simple: a reader should understand the whole manifest in one sitting and be able to run it as written.

One concept

Each example teaches one thing: hello-world teaches inline commands, photo_edit.yml teaches foreach and always. Resist the kitchen sink.

Runnable as written

Real tools, real paths, no placeholders. If the example needs pandoc or darktable-cli, it says so and uses their genuine flags.

Visible graph

The dependency structure should be legible from the YAML alone. If a reader cannot trace source to deliverable, the example hides too much.

Anatomy of an example

examples/visual_design.yml shows the standard shape: variables first, reusable rules second, targets third, operator actions fourth, and deliverables last.

examples/visual_design.yml

# Schema version comes first, always quoted.
netsuke_version: "1.0.0"

# Declare the file set and tool choices once.
vars:
  src_dir: design/svg
  out_dir: build/raster
  inkscape: inkscape
  designs:
    - hero
    - logo

# Rules carry the shared command templates.
rules:
  - name: rasterise
    command: "{{ inkscape }} --export-type=png --export-filename={{ outs }} {{ ins }}"
    description: "Rasterising an SVG file"
  - name: clean
    command: "rm -rf {{ out_dir }}"

# The output directory is a first-class target.
targets:
  - name: "{{ out_dir }}"
    command: "mkdir -p {{ outs }}"

  - foreach: designs
    name: "{{ out_dir }}/{{ item }}.png"
    rule: rasterise
    sources: "{{ src_dir }}/{{ item }}.svg"
    order_only_deps: "{{ out_dir }}"

# Operator tasks live in actions, outside the default graph.
actions:
  - name: clean
    rule: clean

# Defaults name the deliverable, not an abstract label.
defaults:
  - build/raster/hero.png

Manifest conventions

The shipped examples follow a handful of conventions that keep them correct as well as readable. New examples should follow them too.

Declare the file set in `vars`

A named list (designs, pages, chapters) makes growth a one-line change and keeps the graph deterministic. glob('src/*.c') is the right tool when the set should track the filesystem — over source files.

Never glob generated outputs

Templates expand before anything is built, so glob('build/*.o') sees an empty directory on a clean checkout. List generated inputs explicitly, as writing.yml does for its TeX chapters.

Model output directories

Give the output directory its own mkdir -p target and reference it via order_only_deps: it is created first, but touching it never triggers rebuilds.

Actions for operator tasks

clean, run, and preview belong in actions, not targets — useful to a human at the keyboard, never part of the build product.

Small touches that pay off

Give rules a description — it becomes the progress line during the build. Name defaults after concrete deliverables (site/index.html, build/book.pdf) so running bare netsuke produces something a reader can open. Quote netsuke_version so YAML treats it as a string.

Where examples live

Examples are part of the netsuke repository itself, under examples/. Single-file examples are flat YAML manifests named for their domain; examples that need input files get a directory with a Netsukefile.

examples/

hello-world/ (directory: manifest + input files)

Netsukefile

input.txt

basic_c.yml (rules, targets, actions)

website.yml (foreach, order_only_deps)

photo_edit.yml (always, actions)

visual_design.yml (vars-driven tooling)

writing.yml (explicit intermediate files)

Naming

Name the manifest after the domain it demonstrates (photo_edit.yml), not the feature (foreach_demo.yml).
Use snake_case for flat manifests and kebab-case for example directories, matching the existing set.
Keep input fixtures tiny. An example is a teaching aid, not a dataset.

Showcase pages

The strongest examples graduate to full pages in the Examples Hub. Every showcase follows the same four-part structure, so readers always know where to look.

1. Directory structure

A file tree showing inputs, outputs, and the Netsukefile, plus one paragraph on why the example matters.

2. Annotated manifest

The manifest verbatim from the repository, with two or three numbered callouts explaining the load-bearing decisions.

3. Terminal preview

A realistic netsuke build transcript — Ninja-style [1/4] progress lines showing the actual commands.

4. Build flow

Four steps from declaration to deliverable, naming the manifest features that carry each step.

The manifest on the page is the manifest in the repository

Showcase pages quote the shipped example verbatim, label it with its repository path, and link to it on GitHub. If the page needs a different manifest to tell its story, fix the example first — the site never drifts ahead of the code.

Submitting

Examples land through the normal contribution workflow: open an issue to pitch the idea, then a pull request against the repository. A showcase page can follow once the example is merged.

Pre-submission checklist

netsuke build succeeds from a clean checkout
netsuke generate emits the Ninja plan you expect
External tools are named in a comment or the pull request
The manifest demonstrates one concept, stated in one sentence
defaults name concrete deliverables
Repository quality gates pass (make check-fmt lint test)