This is an automated email from the ASF dual-hosted git repository.
guan404ming pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/mahout.git
The following commit(s) were added to refs/heads/main by this push:
new d23be9ab8 docs: fix stale links and Docusaurus relative-link rendering
(#1305)
d23be9ab8 is described below
commit d23be9ab8030e43e726a8bf6716ad3603453b6e8
Author: Tim Hsiung <[email protected]>
AuthorDate: Thu May 14 10:31:02 2026 +0800
docs: fix stale links and Docusaurus relative-link rendering (#1305)
The How to Contribute pages referenced three stale targets on
mahout.apache.org that all return 404, and additional relative-path
links in the source docs were silently rendering as 404 on the built
site:
- guide for making website updates ->
documentation/developers/how-to-update-the-website.html
- wide variety of books and slides -> general/books-tutorials-and-talks.html
- Handling GitHub PRs -> documentation/developers/github
Root cause for the relative-link rendering bug: docusaurus.config.ts
does not set trailingSlash, so Docusaurus serves URLs with a trailing
slash, and a relative href `../community/mailing-lists` from
`/docs/next/about/how-to-contribute/` resolves in the browser to
`/docs/next/about/community/mailing-lists` (404). The proper
Docusaurus fix is markdown links with the .md extension so Docusaurus
statically resolves them to the correct version-aware URL, but
sync-docs.js was stripping the .md extension before Docusaurus saw
the file, defeating that resolution.
Fixes:
- website/scripts/sync-docs.js: stop stripping .md from internal links
in transformLinks(); let Docusaurus handle resolution.
- docs/about/how-to-contribute.md: switch the three `../community/...`
relative links to use a .md extension (lines 15, 85, 144). Drop the
`guide for making website updates` sentence and its [2] reference;
website/README.md is not published to mahout.apache.org so there is
no equivalent page.
- docs/qumat/index.md, docs/qumat/getting-started.md: switch
`../qdp`, `../learning/...` relative links to use the .md
extension, fixing previously silently-broken links from the same
pattern.
- website/versioned_docs/version-0.4/about/how-to-contribute.md:
replace stale http://people.apache.org/~hossman/#private_q (404)
with https://www.apache.org/theapacheway/ (matches next/v0.5).
Drop the `[2]` guide-for-making-website-updates sentence.
- website/versioned_docs/version-0.5/about/how-to-contribute.md:
drop the `[2]` guide-for-making-website-updates sentence.
- Earlier: rewire `Handling GitHub PRs` to the
pr-policy-and-review-guidelines doc, drop the `books and slides`
sentence (no equivalent page exists), and remove
docs/about/how-to-contribute.md from lychee.toml exclude_path.
Verified locally:
- `cd website && npm run build`: no broken-link warnings on the
previously broken paths; rendered hrefs in the built `next` page
resolve to `/docs/next/community/mailing-lists` and
`/docs/next/community/pr-policy-and-review-guidelines`.
- `lychee 0.24.2 --config lychee.toml .`: 95 -> 94 total errors
(removed v0.4 hossman 404; no new failures).
- `pre-commit run --files <changed>` with environment-specific
hooks (clippy/fmt/ty) skipped: end-of-file-fixer and
trailing-whitespace pass.
Closes #1301
Generated-by: GitHub Copilot CLI
Co-authored-by: Copilot <[email protected]>
---
docs/about/how-to-contribute.md | 12 ++++--------
docs/qumat/getting-started.md | 2 +-
docs/qumat/index.md | 6 +++---
lychee.toml | 1 -
website/scripts/sync-docs.js | 6 ------
.../versioned_docs/version-0.4/about/how-to-contribute.md | 10 +++-------
.../versioned_docs/version-0.5/about/how-to-contribute.md | 8 ++------
7 files changed, 13 insertions(+), 32 deletions(-)
diff --git a/docs/about/how-to-contribute.md b/docs/about/how-to-contribute.md
index a231e04f5..4b7aa732f 100644
--- a/docs/about/how-to-contribute.md
+++ b/docs/about/how-to-contribute.md
@@ -12,7 +12,7 @@ of ways to contribute!
<a name="HowToContribute-BeInvolved"></a>
## Get Involved
-Discussions at Apache happen on the mailing list. To get involved, you should
join the [Mahout mailing lists](../community/mailing-lists). In particular:
+Discussions at Apache happen on the mailing list. To get involved, you should
join the [Mahout mailing lists](../community/mailing-lists.md). In particular:
* The **user list** (to help others)
* The **development list** (to join discussions of changes) -- This is the
best place
@@ -46,9 +46,7 @@ where people are working.
Also, documentation is a great way to familiarize yourself with the code
and is always a welcome addition to the codebase and this website. Feel free
to contribute texts and tutorials! Committers will make sure they are added
-to this website, and we have a [guide for making website updates][2].
-We also have a [wide variety of books and slides][3] for learning more about
-machine learning algorithms.
+to this website.
If you are interested in working towards being a committer, general guidelines
are available in the [Apache Community
documentation](https://community.apache.org/contributors/).
@@ -82,7 +80,7 @@ First of all, you need to get the Mahout source code from
[GitHub](https://githu
<a name="HowToContribute-MakingChanges"></a>
## Making Changes
-Before you start, you should send a message to the [Mahout developer mailing
list](../community/mailing-lists)
+Before you start, you should send a message to the [Mahout developer mailing
list](../community/mailing-lists.md)
(note: you have to subscribe before you can post), or file a ticket in our
[issue tracker](https://github.com/apache/mahout/issues).
Describe your proposed changes and check that they fit in with what others are
doing and have planned for the project. Be patient, it may take folks a while
to understand your requirements.
@@ -143,9 +141,7 @@ for improvement (more tests, better javadocs, etc...) then
make the changes on y
thumbs up, that's a good sign for committers when deciding if it's worth
spending time to review it -- and if other people have already put in
effort to improve the docs/tests for an issue, that helps even more.
-For more information see [Handling GitHub
PRs](http://mahout.apache.org/documentation/developers/github).
+For more information see the [PR policy and review
guidelines](../community/pr-policy-and-review-guidelines.md).
[1]: http://www.apache.org/dev/contrib-email-tips
- [2]:
http://mahout.apache.org/documentation/developers/how-to-update-the-website.html
- [3]: http://mahout.apache.org/general/books-tutorials-and-talks.html
diff --git a/docs/qumat/getting-started.md b/docs/qumat/getting-started.md
index 393d874e3..4547e3ff5 100644
--- a/docs/qumat/getting-started.md
+++ b/docs/qumat/getting-started.md
@@ -72,4 +72,4 @@ Refer to repository examples:
- [Basic Gates](./basic-gates)
- [API Reference](./api)
-- [QDP Getting Started](../qdp/getting-started)
+- [QDP Getting Started](../qdp/getting-started.md)
diff --git a/docs/qumat/index.md b/docs/qumat/index.md
index 2c82e47ed..42bfd6254 100644
--- a/docs/qumat/index.md
+++ b/docs/qumat/index.md
@@ -21,6 +21,6 @@ Qumat is a high-level Python library for quantum computing
that provides:
## Related
-- [QDP (Quantum Data Plane)](../qdp)
-- [Quantum Computing Primer](../learning/quantum-computing-primer)
-- [Research Papers](../learning/papers)
+- [QDP (Quantum Data Plane)](../qdp/index.md)
+- [Quantum Computing Primer](../learning/quantum-computing-primer/index.md)
+- [Research Papers](../learning/papers/index.md)
diff --git a/lychee.toml b/lychee.toml
index 62f5ec93a..f5b94fa38 100644
--- a/lychee.toml
+++ b/lychee.toml
@@ -4,7 +4,6 @@ exclude_path = [
"./website/versioned*", # Focus on next version
"./website/static/download/downloads.html", # Should we fix in the future?
"./dev/rc-email-template.md", # Should we fix in the future?
- "./docs/about/how-to-contribute.md", # TODO: fix the links in this file
"./qdp/docs/readers/README.md", # TODO: fix the links in this file
]
fallback_extensions = ["md"]
diff --git a/website/scripts/sync-docs.js b/website/scripts/sync-docs.js
index fd8f7b0dd..b0fe4bdb4 100644
--- a/website/scripts/sync-docs.js
+++ b/website/scripts/sync-docs.js
@@ -165,12 +165,6 @@ function transformLinks(content) {
return match;
}
- // Handle .md file references
- if (url.endsWith('.md')) {
- // Remove .md extension for Docusaurus
- url = url.slice(0, -3);
- }
-
return `[${text}](${url})`;
});
}
diff --git a/website/versioned_docs/version-0.4/about/how-to-contribute.md
b/website/versioned_docs/version-0.4/about/how-to-contribute.md
index a88143d97..548179c9d 100644
--- a/website/versioned_docs/version-0.4/about/how-to-contribute.md
+++ b/website/versioned_docs/version-0.4/about/how-to-contribute.md
@@ -21,7 +21,7 @@ to understand where the project is headed.
Please keep discussions about Mahout on list so that everyone benefits.
Emailing individual committers with questions about specific Mahout issues
-is discouraged. See
[http://people.apache.org/~hossman/#private_q](http://people.apache.org/~hossman/#private_q)
+is discouraged. See
[https://www.apache.org/theapacheway/](https://www.apache.org/theapacheway/)
. Apache has a number of [email tips for contributors][1] as well.
<a name="HowToContribute-WhattoWorkOn?"></a>
@@ -46,9 +46,7 @@ where people are working.
Also, documentation is a great way to familiarize yourself with the code
and is always a welcome addition to the codebase and this website. Feel free
to contribute texts and tutorials! Committers will make sure they are added
-to this website, and we have a [guide for making website updates][2].
-We also have a [wide variety of books and slides][3] for learning more about
-machine learning algorithms.
+to this website.
If you are interested in working towards being a committer, general guidelines
are available in the [Apache Community
documentation](https://community.apache.org/contributors/).
@@ -143,9 +141,7 @@ for improvement (more tests, better javadocs, etc...) then
make the changes on y
thumbs up, that's a good sign for committers when deciding if it's worth
spending time to review it -- and if other people have already put in
effort to improve the docs/tests for an issue, that helps even more.
-For more information see [Handling GitHub
PRs](http://mahout.apache.org/documentation/developers/github).
+For more information see the [PR policy and review
guidelines](https://github.com/apache/mahout/blob/main/docs/community/pr-policy-and-review-guidelines.md).
[1]: http://www.apache.org/dev/contrib-email-tips
- [2]:
http://mahout.apache.org/documentation/developers/how-to-update-the-website.html
- [3]: http://mahout.apache.org/general/books-tutorials-and-talks.html
diff --git a/website/versioned_docs/version-0.5/about/how-to-contribute.md
b/website/versioned_docs/version-0.5/about/how-to-contribute.md
index f43afcd4a..64255056e 100644
--- a/website/versioned_docs/version-0.5/about/how-to-contribute.md
+++ b/website/versioned_docs/version-0.5/about/how-to-contribute.md
@@ -46,9 +46,7 @@ where people are working.
Also, documentation is a great way to familiarize yourself with the code
and is always a welcome addition to the codebase and this website. Feel free
to contribute texts and tutorials! Committers will make sure they are added
-to this website, and we have a [guide for making website updates][2].
-We also have a [wide variety of books and slides][3] for learning more about
-machine learning algorithms.
+to this website.
If you are interested in working towards being a committer, general guidelines
are available in the [Apache Community
documentation](https://community.apache.org/contributors/).
@@ -143,9 +141,7 @@ for improvement (more tests, better javadocs, etc...) then
make the changes on y
thumbs up, that's a good sign for committers when deciding if it's worth
spending time to review it -- and if other people have already put in
effort to improve the docs/tests for an issue, that helps even more.
-For more information see [Handling GitHub
PRs](http://mahout.apache.org/documentation/developers/github).
+For more information see the [PR policy and review
guidelines](https://github.com/apache/mahout/blob/main/docs/community/pr-policy-and-review-guidelines.md).
[1]: http://www.apache.org/dev/contrib-email-tips
- [2]:
http://mahout.apache.org/documentation/developers/how-to-update-the-website.html
- [3]: http://mahout.apache.org/general/books-tutorials-and-talks.html
