docs: fix dead relative links in notebook pages

[dimitri-yatsenko]

Reported: every link on https://docs.datajoint.com/how-to/read-diagrams/ is dead.

Root cause

mkdocs-jupyter does not rewrite relative links inside notebook markdown cells the way MkDocs rewrites them in .md files. Links written in source-file form are emitted verbatim into the HTML.

From the page URL /how-to/read-diagrams/, ../explanation/entity-integrity.md#schema-dimensions resolves to /how-to/explanation/entity-integrity.md — wrong depth and a source-file extension, so 404.

Notebooks have to use built-site URLs instead: directory-style paths, no .md/.ipynb extension, depth counted from the page URL (one extra level, since each page becomes its own directory).

Why the existing check missed it: the lychee job resolves links against the source tree, where ../explanation/entity-integrity.md genuinely exists — so it passes. Only the built output shows what a reader's browser actually requests.

The reported page

src/how-to/read-diagrams.ipynb — all 5 links:

was	now
../explanation/entity-integrity.md#schema-dimensions	../../explanation/entity-integrity/#schema-dimensions
../explanation/entity-integrity.md#dimensions-and-attribute-lineage	../../explanation/entity-integrity/#dimensions-and-attribute-lineage
../reference/specs/diagram.md	../../reference/specs/diagram/
../reference/specs/semantic-matching.md	../../reference/specs/semantic-matching/
../tutorials/basics/02-schema-design.ipynb	../../tutorials/basics/02-schema-design/

Guard against recurrence

scripts/check_links.py checks the built site: every <a href> must resolve to a real file in the build, and any fragment must match an id on the target page. Wired into the Link Check workflow as a second job that builds with --strict and runs it. The source-level lychee job stays — it catches cheaper source rot.

What the guard then found

Running it surfaced links my first grep pass missed, since same-directory links have no ../ prefix to search for:

• how-to/master-part.ipynb — 5 links (define-tables.md, delete-data.md ×2, insert-data.md, model-relationships.ipynb)
• how-to/model-relationships.ipynb — 5 links (define-tables.md, design-primary-keys.md, delete-data.md, read-diagrams.ipynb, master-part.ipynb)
• tutorials/advanced/instances.ipynb — 3 links, source-file form
• tutorials/advanced/sql-comparison.ipynb — correct form, wrong depth
• tutorials/basics/01-first-pipeline.ipynb — ../advanced/instances/, wrong depth

It also surfaced pre-existing anchor rot in .md pages, which had to be cleared for the gate to pass:

• trailing slash inside the fragment — #object-augmented-schemas/, #string-quoting/ — in object-storage-overview, reference/specs/index, migrate-to-v20
• npy-codec pointed at type-system.md#object--schema-addressed-storage; the id is now #object-objectstore-schema-addressed-storage
• object-storage-overview pointed at four anchors that don't exist on their target pages

Please sanity-check these four retargets — the old anchors were gone, so I picked the closest existing section rather than inventing headings:

link	retargeted to
use-object-storage.md#filepath-references	use-object-storage.md#lazy-loading-with-objectref
use-object-storage.md#streaming-access	use-object-storage.md#lazy-loading-with-objectref
use-object-storage.md#migration-patterns	choose-storage-type.md#migration-between-storage-types
choose-storage-type.md#deduplication	choose-storage-type.md#data-not-deduplicated

Verification

Built locally with --strict: zero broken internal links across 142 pages, and MkDocs' own contains a link INFO warnings are gone too.