[PR #1376] [MERGED] docs: fail the build on broken Markdown file-path links #1345

New issue

Closed

opened 2026-10-18 14:19:01 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-18 14:19:01 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/open-webui/docs/pull/1376
Author: @silentoplayz
Created: 9/2/2026
Status: ✅ Merged
Merged: 9/3/2026
Merged by: @Classic298

Base: main ← Head: docs/fail-build-on-broken-markdown-links

📝 Commits (1)

3ad295f docs: fail the build on broken Markdown file-path links

📊 Changes

1 file changed (+3 additions, -0 deletions)

View changed files

📝 docusaurus.config.ts (+3 -0)

📄 Description

Summary

Makes the build fail when a Markdown link written as a file-path points at a file that does not exist. Follows #1373 and #1374, which converted 123 relative links to the file-path form.

 	markdown: {
 		mermaid: true,
+		hooks: {
+			onBrokenMarkdownLinks: "throw",
+		},
 	},

The default is warn, so a Markdown link whose target has moved or been renamed prints a line during the build and ships anyway. onBrokenLinks is already set to throw, but that validates the rendered href rather than the source link, so the two settings cover different things.

232 links now use the file-path form, up from 109 before #1374. That form is only worth adopting if a moved target is caught, which is what this changes.

No linked issue. Follows #1373 and #1374.

Checklist

I have reviewed the relevant documentation and matched the existing style.
This PR meets Open WebUI's contribution standards: it is accurate, relevant to users, narrowly scoped, maintainable, and not promotional content, advertising, lead generation, SEO placement, or a request to list a product, service, provider, integration, gateway, tool, or company primarily for visibility.
I understand that PRs that do not meet these standards may be closed without review and will not be merged. Repeated, low-quality, off-topic, promotional, or intentionally misleading submissions may result in the contributor being blocked from future participation in Open WebUI repositories.

Notes for reviewers

What this catches, and what it does not

I tested both link forms by pointing each at a file that does not exist and building.

Probe	Source	Build result
A	`[probe a](./this-file-does-not-exist.mdx)`	fails, with the file and line number
B	`[probe b](./this-file-also-does-not-exist)`	passes, no message

So this guards the file-path form and nothing else. It would not have caught the 123 dead links fixed in #1373 and #1374, because those were written without an extension and this hook never inspects that form. What it does is keep the fix from rotting. Those links are now file-path links, so a renamed or moved target will stop the build rather than reaching the site.

Probe A reports it like this, which is enough to fix without hunting:

Error: Markdown link with URL `./this-file-does-not-exist.mdx` in source file
"docs/troubleshooting/web-search.mdx" (128:46) couldn't be resolved.

Config key

The installed @docusaurus/core is 3.9.2. The top-level siteConfig.onBrokenMarkdownLinks is deprecated there and logs a migration warning, so this goes in markdown.hooks instead. The build confirms it, printing no deprecation warning.

Verification

npm run build on current main with this setting passes. 419 pages, no broken Markdown links surfaced, no deprecation warning. I then added the two probe links above, rebuilt to confirm the setting actually fires, and reverted them. The only change in this PR is the three config lines.

This PR was prepared with AI copilot assistance. I have thoroughly reviewed and manually tested it.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/docs/pull/1376 **Author:** [@silentoplayz](https://github.com/silentoplayz) **Created:** 9/2/2026 **Status:** ✅ Merged **Merged:** 9/3/2026 **Merged by:** [@Classic298](https://github.com/Classic298) **Base:** `main` ← **Head:** `docs/fail-build-on-broken-markdown-links` --- ### 📝 Commits (1) - [`3ad295f`](https://github.com/open-webui/docs/commit/3ad295f999d322b05a79d942a48c21ee1d536395) docs: fail the build on broken Markdown file-path links ### 📊 Changes **1 file changed** (+3 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docusaurus.config.ts` (+3 -0) </details> ### 📄 Description ## Summary Makes the build fail when a Markdown link written as a file-path points at a file that does not exist. Follows #1373 and #1374, which converted 123 relative links to the file-path form. ```diff markdown: { mermaid: true, + hooks: { + onBrokenMarkdownLinks: "throw", + }, }, ``` The default is `warn`, so a Markdown link whose target has moved or been renamed prints a line during the build and ships anyway. `onBrokenLinks` is already set to `throw`, but that validates the rendered `href` rather than the source link, so the two settings cover different things. 232 links now use the file-path form, up from 109 before #1374. That form is only worth adopting if a moved target is caught, which is what this changes. ## Related issue or discussion No linked issue. Follows #1373 and #1374. ## Checklist - [x] I have reviewed the relevant documentation and matched the existing style. - [x] This PR meets Open WebUI's contribution standards: it is accurate, relevant to users, narrowly scoped, maintainable, and not promotional content, advertising, lead generation, SEO placement, or a request to list a product, service, provider, integration, gateway, tool, or company primarily for visibility. - [x] I understand that PRs that do not meet these standards may be closed without review and will not be merged. Repeated, low-quality, off-topic, promotional, or intentionally misleading submissions may result in the contributor being blocked from future participation in Open WebUI repositories. ## Notes for reviewers **What this catches, and what it does not** I tested both link forms by pointing each at a file that does not exist and building. | Probe | Source | Build result | |---|---|---| | A | `[probe a](./this-file-does-not-exist.mdx)` | fails, with the file and line number | | B | `[probe b](./this-file-also-does-not-exist)` | passes, no message | So this guards the file-path form and nothing else. It would **not** have caught the 123 dead links fixed in #1373 and #1374, because those were written without an extension and this hook never inspects that form. What it does is keep the fix from rotting. Those links are now file-path links, so a renamed or moved target will stop the build rather than reaching the site. Probe A reports it like this, which is enough to fix without hunting: ``` Error: Markdown link with URL `./this-file-does-not-exist.mdx` in source file "docs/troubleshooting/web-search.mdx" (128:46) couldn't be resolved. ``` **Config key** The installed `@docusaurus/core` is 3.9.2. The top-level `siteConfig.onBrokenMarkdownLinks` is deprecated there and logs a migration warning, so this goes in `markdown.hooks` instead. The build confirms it, printing no deprecation warning. **Verification** `npm run build` on current `main` with this setting passes. 419 pages, no broken Markdown links surfaced, no deprecation warning. I then added the two probe links above, rebuilt to confirm the setting actually fires, and reverted them. The only change in this PR is the three config lines. This PR was prepared with AI copilot assistance. I have thoroughly reviewed and manually tested it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-18 14:19:01 +00:00