This is an automated email from the ASF dual-hosted git repository.
jongyoul pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/zeppelin.git
The following commit(s) were added to refs/heads/master by this push:
new 2892d46258 [ZEPPELIN-6628] Add an internal-link check to the docs build
2892d46258 is described below
commit 2892d46258c58cafc22767d0e27dfd30da8fd9e5
Author: chaeyoung kim <[email protected]>
AuthorDate: Mon Aug 10 10:26:38 2026 +0900
[ZEPPELIN-6628] Add an internal-link check to the docs build
### What is this PR for?
Adds a CI job that builds the Jekyll site under `docs/` and validates its
internal links with html-proofer, and fixes the broken links that turning the
check on exposes.
The docs link to each other with relative paths, and nothing validates them
today. No workflow builds the site at all, so a wrong path passes `quick`,
`core` and `frontend` alike and only surfaces once the site is published. Three
such links exist on master.
`JB.BASE_PATH` has to be accounted for. Template links are rendered with
that prefix (`/docs/0.13.0-SNAPSHOT/...`), which exists only on the published
site, so an unadjusted run reports every templated link as broken — 322
internal links, all of them failing. The job reads `BASE_PATH` out of
`_config.yml` and strips it with `--swap-urls`, so links resolve against the
built tree and a version bump does not silently break the job.
Scope is deliberately narrow: `--disable-external` skips external URLs and
`--no-check-internal-hash` skips anchor fragments, both of which fail for
reasons outside this repository and would make the job flaky.
`--allow-missing-href` keeps the `<a name="...">` anchors the docs use as link
targets from being reported as errors.
The job is report-only for now (`continue-on-error: true`), as the issue
asks. Broken links show up in the log without blocking a merge; the comment in
the workflow says when to drop that.
The change has two parts.
**Fix the broken internal links**
- `docs/setup/operation/configuration.md` — raw HTML link, one `../` short.
From `/setup/operation/` it resolved to
`/setup/usage/other_features/customizing_homepage.html`; the page is at
`/usage/...`.
- `docs/setup/deployment/yarn_install.md` — `install.html` resolved to
`/setup/deployment/install.html`; the install guide is at
`/quickstart/install.html`. Matches how `upgrading.md` and
`flink_and_spark_cluster.md` already link it.
- `docs/development/helium/writing_spell.md` — the URL is wrapped in
literal quotes inside the markdown link, so it renders as
`href="%22https://www.npmjs.com/%22"`. Not mentioned on the Jira issue, but
master does not pass the check without it.
**Add the check**
New `.github/workflows/docs.yml`, triggered only on changes under `docs/**`
and on the workflow itself.
### What type of PR is it?
Improvement
### Todos
None. Dropping `continue-on-error` is deliberately left for a follow-up, as
the issue asks; the workflow carries a comment saying so.
### What is the Jira issue?
https://issues.apache.org/jira/browse/ZEPPELIN-6628
### How should this be tested?
The new job runs on this PR, since it touches `docs/**`.
Locally, using the container from `docs/README.md`:
```bash
docker run --rm -v "$PWD/docs:/docs" -w /docs ruby:3.3.5 bash -c '
bundle install &&
bundle exec jekyll build --safe -d _site &&
gem install html-proofer -v 5.2.2 --no-document &&
BASE_PATH=$(ruby -ryaml -e
'"'"'puts(YAML.load_file("_config.yml")["JB"]["BASE_PATH"] || "")'"'"') &&
htmlproofer _site --root-dir _site --checks Links --disable-external \
--no-enforce-https --no-check-internal-hash --allow-missing-href \
--swap-urls "^${BASE_PATH}:"'
```
On master, this reports the three failures above. With this PR applied it
reports none:
```
Checking 321 internal links
Ran on 94 files!
HTML-Proofer finished successfully.
```
Reverting any one of the three link fixes brings back that failure, and
only that one, which confirms the check detects each of them.
### Screenshots (if appropriate)
No
### Questions:
* Does the license files need to update? No. No new dependency ships with
the site — html-proofer is installed in the CI job only, and `docs/Gemfile` is
untouched. The one new file lives under `.github/`, which the rat profile
excludes; `./mvnw apache-rat:check -Prat` passes.
* Is there breaking changes for older versions? No. Documentation and CI
only.
* Does this needs documentation? No.
Closes #5395 from chelsseeey/ZEPPELIN-6628-docs-internal-link-check.
Signed-off-by: Jongyoul Lee <[email protected]>
---
.github/workflows/docs.yml | 62 ++++++++++++++++++++++++++++++++
docs/development/helium/writing_spell.md | 2 +-
docs/setup/deployment/yarn_install.md | 2 +-
docs/setup/operation/configuration.md | 2 +-
4 files changed, 65 insertions(+), 3 deletions(-)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000000..f9d77459a7
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,62 @@
+name: docs
+
+on:
+ push:
+ branches-ignore:
+ - 'dependabot/**'
+ paths:
+ - 'docs/**'
+ - '.github/workflows/docs.yml'
+ pull_request:
+ branches:
+ - master
+ - 'branch-*'
+ paths:
+ - 'docs/**'
+ - '.github/workflows/docs.yml'
+
+permissions:
+ contents: read
+
+jobs:
+ internal-link-check:
+ runs-on: ubuntu-24.04
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+ - name: Set up Ruby
+ uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: '3.3'
+ bundler-cache: true
+ working-directory: docs
+ - name: Build the Jekyll site
+ working-directory: docs
+ run: bundle exec jekyll build --safe -d _site
+ - name: Check internal links
+ working-directory: docs
+ # Report-only: broken links are printed in the log but do not fail the
+ # build yet. Remove this once the job has been green for a while, so
+ # that broken links start blocking merges (ZEPPELIN-6628).
+ continue-on-error: true
+ run: |
+ gem install html-proofer -v 5.2.2 --no-document
+ # Template links are prefixed with JB.BASE_PATH (e.g.
+ # /docs/0.13.0-SNAPSHOT), a prefix that only exists once the site is
+ # published. Strip it so links resolve against the built tree. Read
it
+ # from _config.yml so a version bump does not break this job.
+ BASE_PATH=$(ruby -ryaml -e
'puts(YAML.load_file("_config.yml")["JB"]["BASE_PATH"] || "")')
+ echo "Stripping BASE_PATH prefix: ${BASE_PATH}"
+ # Only internal links are in scope. External URLs are skipped because
+ # they break for reasons outside this repository and would make the
+ # job flaky; anchor fragments are skipped for the same reason. The
+ # --allow-missing-href flag keeps `<a name="...">` anchors, which the
+ # docs use as link targets, from being reported as errors.
+ htmlproofer _site \
+ --root-dir _site \
+ --checks Links \
+ --disable-external \
+ --no-enforce-https \
+ --no-check-internal-hash \
+ --allow-missing-href \
+ --swap-urls "^${BASE_PATH}:"
diff --git a/docs/development/helium/writing_spell.md
b/docs/development/helium/writing_spell.md
index e781a98243..b2988a90ae 100644
--- a/docs/development/helium/writing_spell.md
+++ b/docs/development/helium/writing_spell.md
@@ -63,7 +63,7 @@ Making a new spell is similar to [Helium
Visualization#write-new-visualization](
- Add framework dependency called zeppelin-spell into `package.json`
- Write code using framework
-- Publish your spell to [npm]("https://www.npmjs.com/";)
+- Publish your spell to [npm](https://www.npmjs.com/)
### 1. Create a npm package
diff --git a/docs/setup/deployment/yarn_install.md
b/docs/setup/deployment/yarn_install.md
index 994180126e..4c7e87bf59 100644
--- a/docs/setup/deployment/yarn_install.md
+++ b/docs/setup/deployment/yarn_install.md
@@ -76,7 +76,7 @@ This document assumes Spark 1.6.0 is installed at
/usr/lib/spark.
#### Zeppelin
Checkout source code from
[git://git.apache.org/zeppelin.git](https://github.com/apache/zeppelin.git) or
download binary package from [Download
page](https://zeppelin.apache.org/download.html).
-You can refer [Install](install.html) page for the details.
+You can refer [Install](../../quickstart/install.html) page for the details.
This document assumes that Zeppelin is located under `/home/zeppelin/zeppelin`.
## Zeppelin Configuration
diff --git a/docs/setup/operation/configuration.md
b/docs/setup/operation/configuration.md
index 9588cd25a5..0a53f5179e 100644
--- a/docs/setup/operation/configuration.md
+++ b/docs/setup/operation/configuration.md
@@ -236,7 +236,7 @@ Sources descending by priority:
<td><h6 class="properties">ZEPPELIN_NOTEBOOK_HOMESCREEN_HIDE</h6></td>
<td><h6 class="properties">zeppelin.notebook.homescreen.hide</h6></td>
<td>false</td>
- <td>Hide the note ID set by <code>ZEPPELIN_NOTEBOOK_HOMESCREEN</code> on
the Apache Zeppelin homescreen. <br />For the further information, please read
<a href="../usage/other_features/customizing_homepage.html">Customize your
Zeppelin homepage</a>.</td>
+ <td>Hide the note ID set by <code>ZEPPELIN_NOTEBOOK_HOMESCREEN</code> on
the Apache Zeppelin homescreen. <br />For the further information, please read
<a href="../../usage/other_features/customizing_homepage.html">Customize your
Zeppelin homepage</a>.</td>
</tr>
<tr>
<td><h6 class="properties">ZEPPELIN_WAR_TEMPDIR</h6></td>
