Widget and sidebar blocks

A widget and the sidebar are ordinary Markdown documents whose type (Widget, Sidebar) turns on a special reading. This page is the one declaration of that reading: which blocks exist, how each is written, and the rules that resolve every ambiguity. A document without one of these types is never read this way.

A collection declaration is discovered only at direct collections/<name>.md with type: Collection. The preferred declaration omits items and projects direct Markdown children of /<name>/; an explicit items selector may use path, paths, type or strict query-v1 query mode. Those selectors may source items from any bundle directories without moving or copying their files.

The one syntax: a block is a link to what it shows

---
type: Widget
title: How this card looks
---

- [Goals](collections/goals.md)
- [Pages](../index.md)
- [Collections](collections/)

A link to a file shows that one thing. A link to a folder shows what the folder holds. That single rule gives every "overview" block a natural target — and the file stays useful on GitHub, where a folder link opens the folder and a file link opens the file.

Settings

A block with no settings is a bare link. Optional settings ride the link's invisible trailing comment and change looks, never meaning:

- [Tasks](collections/tasks.md)<!--sb view="Board"-->

Interpretation rules

1. Only list items and paragraphs that are one self-titled link are blocks; a link inside a sentence is a sentence.
2. The link label is the block's visible name; the person's words are never corrected.
3. A target that does not exist draws a plain sentence saying so, and the line is left exactly as written.
4. Ordinary blocks (headings, paragraphs, dividers) are allowed between block links and draw as themselves — a widget may carry a caption.
5. The shell (fold, picture, name, controls, view switcher) is drawn by the product from the widget's kind and is never serialized in the body.