MODEL.md

The site model

php build.php writes build/model.json before it renders (lib/Model.php makes it). Stage-2 templates and the search index read this file; they do not recompute anything. Ordered lists are in reading order.

projects.<phasync|swerve>
  title, url                 the project's Manual page: /topics/<project>/ (proposed; no page is written for it yet)
  getStarted[]               {title, url, summary}: the pages under /get-started/ (shared by both projects)
  manual[]                   the topics, by `order`
    slug, project, title, summary, order, status (draft|stable), url (/topics/<project>/<slug>/)
    introduction             HTML: the body of content/<project>/topics/<slug>.md
    concepts[], guides[]     {title, url, summary}: prose pages with `topic:` and `role:` in the front matter
    symbols[]                {name, full, kind, url, summary, topic, members[]?}: classes, interfaces, traits, enums,
                             functions, and the methods of a facade class (kind "method"). `members` are all the methods
                             of the class, except for a facade class, where they are the methods of this topic only.
    examples[]               every example of the topic's symbols and members, an example plus {symbol, symbolUrl}
  changelog                  {html, releases[{title,id}], pages[{slug,title,html}]}: from the package repos (CHANGELOG.md; pages: upgrading = changelog entries
                             that mention "breaking" or sit under a Breaking heading, planned = docs/roadmap-2.0.md, process = CONTRIBUTING.md + SECURITY.md).
                             A page whose source is missing is absent. Pages are /<project>/changelog/<slug>/.
  sidebars                   the sidebar tree of each sub-section other than the Manual (its tree depends on the page): keys get-started, symbols,
                             symbols/classes, symbols/functions (a view with no symbols is omitted), changelog. {title, ordered, items[]}; item is
                             {title, url}, {label}, or {jump:[{title,url}]} (the A to Z row). Urls are final. Render only draws them.
  index
    symbols[], members[]     every symbol A to Z, then every method A to Z: {name, full, kind, url, summary, topic}

symbols.<full name>          `phasync\Util\WaitGroup`, `Swerve\Swerve::publish`, `phasync\sleep`
  name, kind, url, package, project, summary
  topic, topicSource         slug; "source" (@topic), "map" (topics-map.php, no @topic) or "override" (topics-map.php, @topic disagrees); null when none
  since, deprecated, changed[{version,text}], notes[], warnings[]       markdown
  examples[]                 numbered, in order: @example files, then fenced php blocks of the docblock
                             {n, kind: file|inline, path, caption, code, output, exit, ok, timeout, seconds}
                             output/exit/ok are null for inline blocks (they are shown, not run) and when run with --skip-examples
  breadcrumbs[]              {title, url}: Home, project, topic, (class)
  see_also[]                 at most 10: {name, url, desc, source, code}
                             source is always "" (explicit @see only)
  used_in                    [{name, url, desc}]: guide/concept pages linking the symbol

pages.<url>                  every prose page (symbol pages are in `symbols`)
  title, breadcrumbs[], prev, next ({title,url} or null: within the topic's reading order, topic page, concepts, guides),
  project, topic (null for a page outside the Manual), see_also[] (the page's own `see_also` front matter)

A symbol with no topic has topic: null and a breadcrumb trail without one; lint reports it. URLs are root-relative and are the ones build.php writes, except the /topics/... URLs, which stage 2 must render (a Manual page per project, a page per topic: introduction, concepts, guides, symbols, examples).