decentraland / decentraland/docs
Broken relative links across docs render as external GitHub URLs
- Dominant language
- Wolfram Language
- Stars
- 0
- Forks
- 8
- Avg merge
- 1d 10h
- Merged PRs (30d)
- 21
Description
## Background
Links in page content that point at a **directory** instead of a concrete `.md` file don't resolve to a page in GitBook. Instead of an internal docs link, GitBook silently falls back to an **external link to the file on github.com**, kicking readers out of the docs site and into the repo view.
This was discovered and fixed for the mobile docs in PR #122 (commit `cc086cc`) — the same pattern exists in other places across all docs sections (`creator/`, `creator-esp/`, `contributor/`, root `README.md`), and this issue is for cleaning those up.
## Example
`creator/tutorials/video-emotes.md` contains:
```md
* [Emotes Overview](../wearables-and-emotes/emotes/)
```
Because the target is a folder (trailing `/`, no file), GitBook renders it as:
```html
Emotes Overview
```
**The fix** is to point at the concrete page file:
```md
* [Emotes Overview](../wearables-and-emotes/emotes/README.md)
```
which GitBook resolves to a proper internal link (`/creator/wearables-and-emotes/emotes`). Pick the folder's `README.md` when that's the nav page, or the natural landing page otherwise — PR #122 used `build-for-mobile/mobile-client/overview.md` for the "mobile app" links, for reference.
**Note:** folder-form entries in `SUMMARY.md` are correct and must NOT be changed — they define the navigation. This issue is only about links inside page content.
## How to find them
```bash
grep -rnE '\]\([^)h][^):]*/\)' --include="*.md" . | grep -v "SUMMARY.md" | grep -vE '\]\(https?://'
```
(Matches relative links ending in `/` outside SUMMARY files; currently ~30 hits across the repo.)
## Related variant
The same grep also surfaces a nastier subset: garbled **"See documentation" migration artifacts** like `([See documentation](../../../../))` in `creator/sdk7/interactivity/button-events/register-callback.md` (and mirrors in `creator-esp/`), which render as links to the repo root. These need per-link judgment to restore the originally intended target, not just a mechanical retarget — treat them as a second pass within this issue.
## Acceptance criteria
The detection grep returns no hits in page content, and spot-checking previously affected pages in a GitBook preview shows no in-content link with a `github.com/decentraland/docs` href.
Contributor guide
Research direction
Run the provided grep across Markdown files, excluding SUMMARY.md and external URLs, then inspect the roughly 30 content links in the listed documentation sections. Update directory links to the appropriate README.md or landing page and investigate the migration-artifact links individually. Done means the detection grep has no page-content hits and affected links no longer resolve to GitHub in a GitBook preview.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100