Skip to content

Broken relative links across docs render as external GitHub URLs #160

Description

@EibrielInv

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:

* [Emotes Overview](../wearables-and-emotes/emotes/)

Because the target is a folder (trailing /, no file), GitBook renders it as:

<a href="https://github.com/decentraland/docs/blob/main/creator/wearables-and-emotes/emotes/README.md">Emotes Overview</a>

The fix is to point at the concrete page file:

* [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

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions