You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@zeppelin.apache.org by "jongyoul (via GitHub)" <gi...@apache.org> on 2026/08/03 15:08:13 UTC

[PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

jongyoul opened a new pull request, #5372:
URL: https://github.com/apache/zeppelin/pull/5372

   ### What is this PR for?
   Modernize the versioned documentation build and keep its publication output compatible with `zeppelin-site`.
   
   - Replace `github-pages` / Jekyll 3.9.5 / Redcarpet with Jekyll 4.4.1 and Kramdown GFM.
   - Make Docker the documented environment for dependency updates, preview, and production builds.
   - Exclude build-only files from `_site` and document the Zeppelin-to-`zeppelin-site` publication boundary.
   - Remove obsolete third-party analytics, comment, sharing, feed, and externally hosted asset integrations.
   - Preserve Apache Zeppelin's approved ASF Matomo site ID 69 only in `--safe` production builds.
   - Add a generated-site check for non-ASF embedded resources and unapproved trackers.
   
   This also prevents the build manifests covered by ZEPPELIN-6431 from being copied into future versioned documentation snapshots. Cleaning historical snapshots remains work in `apache/zeppelin-site`.
   
   ### What type of PR is it?
   Improvement
   
   ### Todos
   * [x] Upgrade the Jekyll and Ruby toolchain.
   * [x] Document and verify the Docker-only build.
   * [x] Remove legacy integrations and empty Atom/RSS feeds.
   * [x] Preserve approved ASF Matomo tracking for production docs.
   * [x] Verify generated output and external-resource policy.
   
   ### What is the Jira issue?
   * https://issues.apache.org/jira/browse/ZEPPELIN-6432
   * Related: https://issues.apache.org/jira/browse/ZEPPELIN-6431
   
   ### How should this be tested?
   From `docs/`:
   
   ```bash
   docker run --rm \
     -v "$PWD:/docs" \
     -w /docs \
     ruby:4.0.6 \
     bash -lc "bundle install && bundle exec jekyll build --safe"
   ```
   
   Then:
   
   ```bash
   docker run --rm \
     -v "$PWD:/docs:ro" \
     -w /docs \
     ruby:4.0.6 \
     ruby check_external_resources.rb _site
   ```
   
   The final verification generated 94 HTML files with Jekyll 4.4.1, emitted no build warnings, retained ASF Matomo site ID 69 only in the safe build, and produced no Atom/RSS or build-manifest output.
   
   ### Screenshots (if appropriate)
   Not applicable; this PR does not change the documentation CSS or page layout.
   
   ### Questions:
   * Does the license files need to update? No.
   * Is there breaking changes for older versions? No runtime behavior changes; this affects the documentation build and generated output.
   * Does this needs documentation? `docs/README.md` and `docs/AGENTS.md` are updated.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "jongyoul (via GitHub)" <gi...@apache.org>.
jongyoul commented on PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#issuecomment-5231861723

   Thanks for the thorough review, @kimyenac!
   
   I've addressed your feedback in the latest commit:
   - Fixed the unclosed `<tr>` tags in `docs/interpreter/spark.md` and the mis-closed `</td>` tag in `docs/usage/rest_api/interpreter.md`.
   - Added `show_warnings: true` under `kramdown:` in `docs/_config.yml` to help catch HTML structure/markup warnings early.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "jongyoul (via GitHub)" <gi...@apache.org>.
jongyoul commented on PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#issuecomment-5264560768

   @pan3793 @ParkGyeongTae @tbonelee @voidmatcha Could you please check it lightly? it's only for building /docs. 🙏 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "kimyenac (via GitHub)" <gi...@apache.org>.
kimyenac commented on code in PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#discussion_r3734168822


##########
docs/_config.yml:
##########
@@ -2,11 +2,11 @@
 # For more see: http://jekyllrb.com/docs/permalinks/
 permalink: /:categories/:year/:month/:day/:title
 
-exclude: [".rvmrc", ".rbenv-version", "README.md", "Rakefile", "changelog.md", "vendor", "node_modules", "scss"]
+exclude: [".rvmrc", ".rbenv-version", "AGENTS.md", "Gemfile", "Gemfile.lock", "README.md", "Rakefile", "changelog.md", "check_external_resources.rb", "vendor", "node_modules", "scss"]
 highlighter: rouge
-markdown: redcarpet
-redcarpet:
-  extensions: ["tables"]
+markdown: kramdown
+kramdown:

Review Comment:
   `kramdown-parser-gfm` defaults `hard_wrap` to `true`, while the previous Redcarpet configuration (`extensions: ["tables"]`) did not enable hard wrapping. With this switch, every soft line break inside a paragraph becomes a `<br />.`
   
   This is not limited to a few pages. Every one of the 96 .md files under docs/ wraps prose across multiple lines, and I count roughly 1,500 affected prose lines once code fences, lists and tables are excluded (the heaviest are `usage/other_features/zeppelin_context.md`, `interpreter/flink.md` and `usage/zeppelin_sdk/session_api.md`). The currently published 0.12.0 pages contain no `<br />` inside paragraphs, so this would be a visible change in rendering for the whole documentation set.
   
   Could we pin the option explicitly?
   
   ```
   kramdown:
     input: GFM
     hard_wrap: false
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "kimyenac (via GitHub)" <gi...@apache.org>.
kimyenac commented on code in PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#discussion_r3734689619


##########
docs/_config.yml:
##########
@@ -2,11 +2,11 @@
 # For more see: http://jekyllrb.com/docs/permalinks/
 permalink: /:categories/:year/:month/:day/:title
 
-exclude: [".rvmrc", ".rbenv-version", "README.md", "Rakefile", "changelog.md", "vendor", "node_modules", "scss"]
+exclude: [".rvmrc", ".rbenv-version", "AGENTS.md", "Gemfile", "Gemfile.lock", "README.md", "Rakefile", "changelog.md", "check_external_resources.rb", "vendor", "node_modules", "scss"]
 highlighter: rouge
-markdown: redcarpet
-redcarpet:
-  extensions: ["tables"]
+markdown: kramdown

Review Comment:
   I compared this branch's generated site against the same docs sources built with Jekyll 3.9.5 and Redcarpet (`Gemfile` swapped, `markdown: redcarpet` restored, docs content untouched). Two pages lose headings under Kramdown, both from unclosed `<tr>` tags in HTML that already existed in the docs. Redcarpet passed the raw HTML through, while Kramdown parses the structure, so the markdown after an open row is emitted unprocessed.
   
   - [`docs/interpreter/spark.md`](https://github.com/apache/zeppelin/blob/43319ce486a61d495dd0dd198fd17386a08320f0/docs/interpreter/spark.md#L131-L149): lines 135 and 140 are `<tr>` where `</tr>` was meant, and the row opened on line 141 is never closed. Everything from line 264 to the end of the page then comes out as raw markdown.
   - [`docs/usage/rest_api/interpreter.md`](https://github.com/apache/zeppelin/blob/43319ce486a61d495dd0dd198fd17386a08320f0/docs/usage/rest_api/interpreter.md#L611-L623): line 623 is `</td>` where `</tr>` was meant, leaving the row opened on line 611 unclosed.
   
   I applied both fixes and rebuilt:
   
   | page | build | `h2`/`h3` | raw markdown emitted |
   | --- | --- | --: | --- |
   | `interpreter/spark.html` | Redcarpet | 20 | none |
   | | Kramdown, current | **4** | 20 headings, 10 links |
   | | Kramdown, fixed | 20 | none |
   | `usage/rest_api/interpreter.html` | Redcarpet | 13 | none |
   | | Kramdown, current | **12** | 1 heading |
   | | Kramdown, fixed | 13 | none |
   
   Diffing the whole generated site before and after the fix, only those two pages change and the other 92 are identical. A scan for unclosed `<tr>` across `docs/` turns up only these two files.
   
   10 literal backticks remain on the Spark page and 210 on the interpreter page after the fix. Those come from a separate pattern, markdown written inside hand-written HTML tables, which I have not looked into yet.
   
   Turning on `kramdown: show_warnings: true` produces 75 warnings across 22 files, including the mis-nested `tr`, `table` and `td` ones for both files above (6 and 3). With that enabled, and perhaps failing the docs build when the generated site still contains literal backticks or `^#{2,4} ` sequences, I think this kind of problem could be caught early!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "pan3793 (via GitHub)" <gi...@apache.org>.
pan3793 commented on code in PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#discussion_r3765061058


##########
docs/AGENTS.md:
##########
@@ -0,0 +1,187 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# AGENTS.md
+
+> Scoped guidance for work under `docs/`. This file complements the
+> repository-root `AGENTS.md`.
+
+## Scope And Ownership
+
+- `docs/` is the source for Apache Zeppelin's versioned product documentation.
+- The main `zeppelin.apache.org` website is maintained in
+  `apache/zeppelin-site`; its homepage does not need to use the same generator
+  as these versioned docs.
+- Markdown, layouts, includes, and assets in this directory are built here.
+  The generated site is written to `docs/_site/`.
+- `docs/_site/` is generated and gitignored. Never edit or commit it.
+
+## Build Model
+
+The current build is:
+
+```text
+docs sources + docs/_config.yml
+  -> Jekyll from docs/Gemfile.lock
+  -> docs/_site/
+  -> zeppelin-site/docs/<version>/ during a separate publication step
+```
+
+- `Gemfile` declares Jekyll and its documentation build dependencies.
+- `Gemfile.lock` pins the actual Ruby dependency versions. The Docker commands
+  use `bundle exec` so the pinned Jekyll version is used.
+- `_config.yml` supplies `ZEPPELIN_VERSION` and `JB.BASE_PATH`.
+- `_includes/JB/setup` applies `JB.BASE_PATH` only for a safe build. Therefore
+  a publication build must include `--safe`.
+- `Rakefile` contains legacy Jekyll-Bootstrap helpers. It is not the primary
+  build entry point; use the Docker commands below.
+- The Maven build does not generate this site.
+- Docker is the supported build environment. Do not install or run Ruby,
+  Bundler, or Jekyll directly on the host.
+
+## Preview And Build
+
+Preview with Docker:
+
+```bash
+cd docs
+docker run --rm -it \
+  -v "$PWD:/docs" \

Review Comment:
   docker inside uses `root` (uid 0), so the output files will be owned by `root` too?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "jongyoul (via GitHub)" <gi...@apache.org>.
jongyoul commented on code in PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#discussion_r3767119465


##########
docs/AGENTS.md:
##########
@@ -0,0 +1,187 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# AGENTS.md
+
+> Scoped guidance for work under `docs/`. This file complements the
+> repository-root `AGENTS.md`.
+
+## Scope And Ownership
+
+- `docs/` is the source for Apache Zeppelin's versioned product documentation.
+- The main `zeppelin.apache.org` website is maintained in
+  `apache/zeppelin-site`; its homepage does not need to use the same generator
+  as these versioned docs.
+- Markdown, layouts, includes, and assets in this directory are built here.
+  The generated site is written to `docs/_site/`.
+- `docs/_site/` is generated and gitignored. Never edit or commit it.
+
+## Build Model
+
+The current build is:
+
+```text
+docs sources + docs/_config.yml
+  -> Jekyll from docs/Gemfile.lock
+  -> docs/_site/
+  -> zeppelin-site/docs/<version>/ during a separate publication step
+```
+
+- `Gemfile` declares Jekyll and its documentation build dependencies.
+- `Gemfile.lock` pins the actual Ruby dependency versions. The Docker commands
+  use `bundle exec` so the pinned Jekyll version is used.
+- `_config.yml` supplies `ZEPPELIN_VERSION` and `JB.BASE_PATH`.
+- `_includes/JB/setup` applies `JB.BASE_PATH` only for a safe build. Therefore
+  a publication build must include `--safe`.
+- `Rakefile` contains legacy Jekyll-Bootstrap helpers. It is not the primary
+  build entry point; use the Docker commands below.
+- The Maven build does not generate this site.
+- Docker is the supported build environment. Do not install or run Ruby,
+  Bundler, or Jekyll directly on the host.
+
+## Preview And Build
+
+Preview with Docker:
+
+```bash
+cd docs
+docker run --rm -it \
+  -v "$PWD:/docs" \

Review Comment:
   As you mentioned, it was root. I added current user's uid/gid.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "kimyenac (via GitHub)" <gi...@apache.org>.
kimyenac commented on code in PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#discussion_r3734168822


##########
docs/_config.yml:
##########
@@ -2,11 +2,11 @@
 # For more see: http://jekyllrb.com/docs/permalinks/
 permalink: /:categories/:year/:month/:day/:title
 
-exclude: [".rvmrc", ".rbenv-version", "README.md", "Rakefile", "changelog.md", "vendor", "node_modules", "scss"]
+exclude: [".rvmrc", ".rbenv-version", "AGENTS.md", "Gemfile", "Gemfile.lock", "README.md", "Rakefile", "changelog.md", "check_external_resources.rb", "vendor", "node_modules", "scss"]
 highlighter: rouge
-markdown: redcarpet
-redcarpet:
-  extensions: ["tables"]
+markdown: kramdown
+kramdown:

Review Comment:
   `kramdown-parser-gfm` defaults `hard_wrap` to `true`, while the previous Redcarpet configuration (`extensions: ["tables"]`) did not enable hard wrapping. With this switch, every soft line break inside a paragraph becomes a `<br />.`
   
   This is not limited to a few pages. Every one of the 96 .md files under docs/ wraps prose across multiple lines, and I count roughly 1,500 affected prose lines once code fences, lists and tables are excluded (the heaviest are `usage/other_features/zeppelin_context.md`, `interpreter/flink.md` and `usage/zeppelin_sdk/session_api.md`). The currently published 0.12.0 pages contain no `<br />` inside paragraphs, so this would be a visible change in rendering for the whole documentation set.
   
   Could we pin the option explicitly?
   
   ```
   kramdown:
     input: GFM
     hard_wrap: false
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "jongyoul (via GitHub)" <gi...@apache.org>.
jongyoul commented on code in PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#discussion_r3766901468


##########
docs/AGENTS.md:
##########
@@ -0,0 +1,187 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# AGENTS.md
+
+> Scoped guidance for work under `docs/`. This file complements the
+> repository-root `AGENTS.md`.
+
+## Scope And Ownership
+
+- `docs/` is the source for Apache Zeppelin's versioned product documentation.
+- The main `zeppelin.apache.org` website is maintained in
+  `apache/zeppelin-site`; its homepage does not need to use the same generator
+  as these versioned docs.
+- Markdown, layouts, includes, and assets in this directory are built here.
+  The generated site is written to `docs/_site/`.
+- `docs/_site/` is generated and gitignored. Never edit or commit it.
+
+## Build Model
+
+The current build is:
+
+```text
+docs sources + docs/_config.yml
+  -> Jekyll from docs/Gemfile.lock
+  -> docs/_site/
+  -> zeppelin-site/docs/<version>/ during a separate publication step
+```
+
+- `Gemfile` declares Jekyll and its documentation build dependencies.
+- `Gemfile.lock` pins the actual Ruby dependency versions. The Docker commands
+  use `bundle exec` so the pinned Jekyll version is used.
+- `_config.yml` supplies `ZEPPELIN_VERSION` and `JB.BASE_PATH`.
+- `_includes/JB/setup` applies `JB.BASE_PATH` only for a safe build. Therefore
+  a publication build must include `--safe`.
+- `Rakefile` contains legacy Jekyll-Bootstrap helpers. It is not the primary
+  build entry point; use the Docker commands below.
+- The Maven build does not generate this site.
+- Docker is the supported build environment. Do not install or run Ruby,
+  Bundler, or Jekyll directly on the host.
+
+## Preview And Build
+
+Preview with Docker:
+
+```bash
+cd docs
+docker run --rm -it \
+  -v "$PWD:/docs" \

Review Comment:
   @pan3793 Oh... Let me check it!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "jongyoul (via GitHub)" <gi...@apache.org>.
jongyoul merged PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] [ZEPPELIN-6432] Modernize the Jekyll documentation build [zeppelin]

Posted by "jongyoul (via GitHub)" <gi...@apache.org>.
jongyoul commented on PR #5372:
URL: https://github.com/apache/zeppelin/pull/5372#issuecomment-5274273585

   Merged into master (0f4991d6).


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: reviews-unsubscribe@zeppelin.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org