Skip to content

docs: fix broken example links after examples reorganization#8102

Merged
steveruizok merged 1 commit intomainfrom
mitja/fix-example-links
Feb 27, 2026
Merged

docs: fix broken example links after examples reorganization#8102
steveruizok merged 1 commit intomainfrom
mitja/fix-example-links

Conversation

@MitjaBezensek
Copy link
Copy Markdown
Contributor

@MitjaBezensek MitjaBezensek commented Feb 26, 2026

Closes #8099

PR #7957 reorganized examples from flat apps/examples/src/examples/{name} into category subdirectories (shapes/tools/, data/assets/, events/, ui/, etc.). All ~115 "Related examples" GitHub links across 40 docs files now 404. This PR updates every link to use the new paths.

Also fixes 2 misnamed example references in default-shapes.mdx:

  • custom-stylesshapes/tools/shape-with-custom-styles
  • shape-optionsconfiguration/configure-shape-util

@steveruizok we sometimes point to hosted examples and sometimes to code on github, not sure if intentional or not?

Change type

  • bugfix

Test plan

  1. Open any docs page with "Related examples" links (e.g. /sdk-features/shapes, /sdk-features/tools, /sdk-features/deep-links)
  2. Click the GitHub example links
  3. Verify they resolve to the correct example directory on GitHub

Release notes

  • Fix ~115 broken GitHub example links across SDK documentation

Note

Low Risk
Low risk: documentation-only changes that update URLs and a couple of example name corrections, with no runtime or API impact.

Overview
Fixes SDK docs and release notes that linked to example directories that were moved in the examples reorg.

Updates "Related examples" links across many sdk-features/*.mdx pages to point at the new categorized paths (e.g. ui/, events/, configuration/, editor-api/, shapes/tools/, data/assets/, use-cases/, layout/). Also corrects a couple of misnamed example references in default-shapes.mdx and updates the v4.3.0 release note link for the pin bindings example.

Written by Cursor Bugbot for commit de7a306. This will update automatically on new commits. Configure here.

@huppy-bot huppy-bot bot added the bugfix Bug fix label Feb 26, 2026
@vercel
Copy link
Copy Markdown

vercel bot commented Feb 26, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
examples Building Building Preview Feb 26, 2026 5:14pm
tldraw-docs Building Building Preview Feb 26, 2026 5:14pm
4 Skipped Deployments
Project Deployment Actions Updated (UTC)
analytics Ignored Ignored Feb 26, 2026 5:14pm
chat-template Skipped Skipped Feb 26, 2026 5:14pm
tldraw-shader Skipped Skipped Feb 26, 2026 5:14pm
workflow-template Skipped Skipped Feb 26, 2026 5:14pm

Request Review

@steveruizok
Copy link
Copy Markdown
Collaborator

Looks good, great catch. I might have to add that broken link checker to the docs build process.

@steveruizok steveruizok added this pull request to the merge queue Feb 27, 2026
Merged via the queue into main with commit ce797eb Feb 27, 2026
28 checks passed
@steveruizok steveruizok deleted the mitja/fix-example-links branch February 27, 2026 06:01
huppy-bot bot pushed a commit that referenced this pull request Feb 27, 2026
Closes #8099

PR #7957 reorganized examples from flat
`apps/examples/src/examples/{name}` into category subdirectories
(`shapes/tools/`, `data/assets/`, `events/`, `ui/`, etc.). All ~115
"Related examples" GitHub links across 40 docs files now 404. This PR
updates every link to use the new paths.

Also fixes 2 misnamed example references in `default-shapes.mdx`:
- `custom-styles` → `shapes/tools/shape-with-custom-styles`
- `shape-options` → `configuration/configure-shape-util`

@steveruizok we sometimes point to hosted examples and sometimes to code
on github, not sure if intentional or not?

### Change type

- [x] `bugfix`

### Test plan

1. Open any docs page with "Related examples" links (e.g.
`/sdk-features/shapes`, `/sdk-features/tools`,
`/sdk-features/deep-links`)
2. Click the GitHub example links
3. Verify they resolve to the correct example directory on GitHub

### Release notes

- Fix ~115 broken GitHub example links across SDK documentation

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: documentation-only changes that update URLs and a couple of
example name corrections, with no runtime or API impact.
> 
> **Overview**
> Fixes SDK docs and release notes that linked to example directories
that were moved in the examples reorg.
> 
> Updates "Related examples" links across many `sdk-features/*.mdx`
pages to point at the new categorized paths (e.g. `ui/`, `events/`,
`configuration/`, `editor-api/`, `shapes/tools/`, `data/assets/`,
`use-cases/`, `layout/`). Also corrects a couple of misnamed example
references in `default-shapes.mdx` and updates the v4.3.0 release note
link for the pin bindings example.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
de7a306. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
github-merge-queue bot pushed a commit that referenced this pull request Feb 28, 2026
… 134 broken links (#8103)

In order to catch broken internal links before they ship (like the ones
fixed in #8102), this PR replaces the `linkinator`-based HTTP crawler
with a static checker that validates links against the content database.
The old checker required a running server, couldn't fail the build, and
missed most broken links. The new checker runs after
`refresh-everything` and before `next build`, failing early if any
broken links are found.

Along the way, this fixes all 134 broken internal links found across the
docs:
- 25 content files with stale `/docs/*` paths (should be
`/sdk-features/*`), wrong heading anchors, double-prefixed paths, and
renamed example links
- API doc generator skipping `TypeAlias`/`Interface` namespace members
(the `// TODO: document these` that caused `T.Validatable` etc. to
generate broken links)
- Namespace member path generation producing standalone paths like
`T-Validatable` instead of anchor links like `T#Validatable`

The checker uses a `--fail` flag to control behavior: `yarn check-links
--fail` (used in `build`) exits non-zero on broken links, while `yarn
check-links` (used in dev) only warns. This ensures broken links never
block the dev server from starting.

Additionally, this adds a standalone `yarn check-external-links` script
for manually checking external (HTTP/HTTPS) links across all docs
content. It deduplicates URLs, uses HEAD with GET fallback (30s timeout,
10 concurrent requests), and retries transient failures with backoff. A
skip list filters out domains that block automated requests (npmjs.com,
shadertoy.com). This replaces the external link checking that was
previously handled by linkinator but is too slow/flaky for the build
pipeline.

Also refactors the hardcoded Framer path prefixes into a shared
`fetchFramerPaths()` utility that fetches the live Framer sitemap. Both
the link checker and `app/sitemap.ts` now use this, so the list stays up
to date automatically.

Fixes a broken external link to the removed `custom-toolbar` example in
the v2.1.0 release notes.

### Change type

- [x] `improvement`

### Test plan

1. `cd apps/docs && yarn refresh-everything && yarn check-links` —
should pass with 0 broken links (warnings only)
2. `yarn check-links --fail` — same result but would exit 1 if any
broken links existed
3. Manually add a broken link to a content file (e.g.
`[test](/nonexistent)`) and run `yarn check-links --fail` — should exit
1 with the broken link reported
4. Run `yarn build` from `apps/docs` — check-links runs with `--fail`
before `next build`
5. `yarn check-external-links` — checks all ~630 unique external URLs,
reports broken ones

- [ ] Unit tests
- [ ] End to end tests

### Release notes

- Fix 134 broken internal links across SDK docs, starter kits, and API
reference
- Add static broken link checker to docs build pipeline (replaces
linkinator)
- Add standalone external link checker script (`yarn
check-external-links`)
- Document `TypeAlias` and `Interface` members within API reference
namespaces
github-merge-queue bot pushed a commit that referenced this pull request Mar 25, 2026
#8276)

In order to stop docs-only hotfixes from triggering unwanted npm patch
releases, this PR adds `yarn refresh-assets --force` before the
`getAnyPackageDiff()` check in `publish-patch.ts`.

### Root cause

PR #8204 added `.yarn/install-state.gz` to the CI cache. When Yarn
determines that the install state hasn't changed (e.g. `node_modules` is
already populated and no dependencies changed), it [skips lifecycle
scripts](https://yarnpkg.com/advanced/lifecycle-scripts) including
`postinstall` ([related
discussion](yarnpkg/berry#5924)). This
means the `postinstall` hook (`husky install && yarn refresh-assets`)
never runs.

Without `refresh-assets`, the gitignored asset directories in
`@tldraw/assets` (`embed-icons/`, `fonts/`, `icons/`, `translations/`)
don't exist on disk. The `getAnyPackageDiff()` guard runs `yarn pack`
which produces a tarball missing these dirs (14 files), while the
npm-published tarball has them (265 files) — always finding a diff,
always publishing.

**Before #8204 (working):** PR #8102 docs hotfix cherry-picked to v4.4.x
— publish-patch skipped correctly, no version bump.

**After #8204 (broken):** PRs #8263 and #8270 docs hotfixes
cherry-picked to v4.5.x — both triggered unwanted npm publishes (v4.5.1
and v4.5.2).

### Why this approach

Considered three options:
1. **Remove `install-state.gz` from cache** — doesn't actually help;
Yarn skips postinstall based on dependency changes, not just the state
file
2. **Add `refresh-assets` to the setup action** — overkill; lazyrepo
already auto-runs it as a dependency of `build`, `build-types`, and
`dev`
3. **Add `refresh-assets` to `publish-patch.ts`** — targeted fix
matching what `trigger-sdk-hotfix.ts` already does (line 98)

Option 3 is the right call. `publish-patch.ts` is the only workflow
confirmed broken — everything else is protected by either lazyrepo's
dependency graph or explicit `refresh-assets` calls in the workflow
YAML.

### Change type

- [x] `bugfix`

### Test plan

Verified locally:
1. Removed asset dirs to simulate CI with warm cache (no postinstall)
2. `yarn pack` on `@tldraw/assets` → 14 files
3. Ran `yarn refresh-assets --force`
4. `yarn pack` again → 265 files

On a release branch with only docs changes, `getAnyPackageDiff()` should
now return `null` → "No packages have changed, skipping release" → no
publish.

### Code changes

| Section        | LOC change |
| -------------- | ---------- |
| Config/tooling | +4 / -0    |
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bugfix Bug fix docs-hotfix-please ⚙️ Triggers docs hotfix release after merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Example links in docs are broken after examples reorganization

2 participants