GitbookIO / GitbookIO/gitbook

Broken Internal Links Render as GitHub URLs Instead of Showing Error

Open
#3,850 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
TypeScript
Stars
29k
Forks
4k
Avg merge
1d 2h
Merged PRs (30d)
71

Description

When a GitBook site is synced bidirectionally with GitHub, broken internal file references (mentions) are incorrectly rendered as links to the GitHub repository instead of being handled as broken links or showing an error message.

Current Behavior

The broken internal reference is automatically converted to a GitHub repository URL pointing to the non-existent file path.

Example markdown referencing a no longer existing file:

See further documentation [mytool.md](mytool.md "mention")

This results in the rendered documentation on the GitBook site to look like this with a fully rendered GitHub link:

See further documentation on https://github.com/<githubuser>/<githubrepo>/blob/main/documentation/mytool.md

(with the full link explicitly embedded into the text instead of being placed behind the "mytool" text)

The link is clickable but obviously results in a 404 error, as the file obviously doesn't exist in the repository.

Expected Behavior

When a Markdown file references a non-existent local file using the mention syntax, GitBook should:

  • Display a broken link indicator, OR
  • Show an error/warning in the editor, OR
  • Render the original link as plain text

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing bidirectional GitHub synchronization and the Markdown mention handling for broken local file references such as mytool.md. Reproduce the example and inspect how the missing path becomes a GitHub repository URL. Done means a nonexistent internal reference is not rendered as a clickable 404 GitHub URL, but instead is shown as broken, warned about, or left as plain text.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, markdown, typescript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.