gridaco Links (engine repo)
A link is correct or broken at the surface it is rendered on, for that surface's audience — not where the text lives in the repo. Before you write any link: (1) where is this text rendered? (2) who reads it there? (3) when they click, where does it resolve from that host — and is that the thing you meant?
Surfaces in this repo
| Surface | Lives in | Audience |
|---|---|---|
| GitHub (repo browse) | everything — incl. docs/wg/** (also published by this repo's www/ docs app, which resolves the same .md-suffixed relative links; GitHub remains the canonical host) |
engine developers |
npm (npmjs.com) |
crates/grida-canvas-wasm package README |
package users |
| Raw / no host | IDE, stack traces, compiled output | whoever has it |
First-party hosts
| URL | What |
|---|---|
https://github.com/gridaco/nothing |
This repo. File → …/blob/main/<path>; dir → …/tree/main/<path>; main only, never a SHA |
https://github.com/gridaco/grida |
The product monorepo (editor, packages, service docs). Same file/dir forms |
https://grida.co |
The product · https://grida.co/docs = the product docs site (publishes grida's docs tree) |
Decision table
| Rendered in | Target | Use |
|---|---|---|
| anywhere in this repo | anything in this repo (crates, docs/wg, fixtures, format) | relative repo path — same host (GitHub) everywhere |
| anywhere in this repo | a grida-repo file/dir | absolute `https://github.com/gridaco/grida/blob |
| anywhere in this repo | a published grida docs page (staying clusters: platform, ai, …) | hosted URL https://grida.co/docs/<path> |
| npm package README | anything in-repo | absolute https://github.com/gridaco/nothing/blob/main/<path> — relative dies on npmjs.com |
| any | external | https://… as-is |
Hard rules
- Never author
https://grida.co/docs/wg/<engine-cluster>/…links. The docs site does not publish this repo's wg tree (canvas, format, research, engine feat-*). Old published URLs survive via a redirect shim in grida — do not author new links through a redirect; use the same-repo relative path (in-repo surfaces) or this repo's absolute GitHub URL (external surfaces). - Cross-repo links are always absolute. A relative path can never reach the other repo.
mainonly — never pin a commit/branch SHA.- Cross-host
#fragment: link the file, not a guessed anchor, unless verified in the target host's slug scheme. - No local-only references — clean them before commit: absolute machine
paths (
/Users/...),/tmp, untracked or gitignored files (fixtures/local/**may be described as local-only, never linked as if it resolves). Ifgit ls-filesdoesn't show it and it isn't a public URL, it does not exist for the audience.