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:

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:

cd docs
docker run --rm -it \
  --user "$(id -u):$(id -g)" \
  -e HOME=/usr/local/bundle \
  -e BUNDLE_FROZEN=true \
  -v "$PWD:/docs" \
  -w /docs \
  -p '4000:4000' \
  ruby:4.0.6 \
  bash -lc "bundle install && bundle exec jekyll serve --watch --host 0.0.0.0"

Open http://localhost:4000. The preview intentionally runs without --safe, so links are rooted at / instead of the production version path. The container uses the current user‘s UID and GID so generated files remain owned by that user on the host. The Ruby image’s writable gem directory is also used as the container home for that user.

Build the publication artifact with Docker:

cd docs
docker run --rm \
  --user "$(id -u):$(id -g)" \
  -e HOME=/usr/local/bundle \
  -e BUNDLE_FROZEN=true \
  -v "$PWD:/docs" \
  -w /docs \
  ruby:4.0.6 \
  bash -lc "bundle install && bundle exec jekyll build --safe"

The output must be under _site/, and generated links and assets must use the JB.BASE_PATH configured in _config.yml.

When Gemfile changes, update Gemfile.lock inside Docker:

cd docs
docker run --rm \
  --user "$(id -u):$(id -g)" \
  -e HOME=/usr/local/bundle \
  -v "$PWD:/docs" \
  -w /docs \
  ruby:4.0.6 \
  bundle lock --update

Run the publication build after updating the lockfile.

Authoring Conventions

  • Preserve the ASF license header in every new source file.

  • Follow the front matter used by nearby pages:

    ---
layout: page
title: "Page title"
description: "Short description"
group: section/subsection
---

  • Include {% include JB/setup %} before page content when following the existing page layout.

  • Prefix internal site links and assets with {{BASE_PATH}} when an absolute site path is needed. Production docs are hosted below /docs/<version>/, not at the domain root.

  • Update _includes/themes/zeppelin/_navigation.html when a page must appear in the global documentation navigation.

  • Keep filenames, headings, and link targets stable unless the task explicitly includes redirects or link migration.

  • Check the corresponding source code or configuration template when documenting runtime behavior. Do not infer current behavior from an older documentation page.

Version Handling

  • ZEPPELIN_VERSION and JB.BASE_PATH in _config.yml must identify the same version.
  • dev/change_zeppelin_version.sh updates both values as part of a repository version change. Do not change them for an ordinary documentation edit.
  • Before producing release docs, verify that JB.BASE_PATH is exactly /docs/<release-version>.

Publication Boundary

  • Building this directory does not publish the website.
  • The generated _site/ tree is copied into apache/zeppelin-site/docs/<version>/ by separate release/site work.
  • The zeppelin-site repository owns the homepage, ASF staging/publishing, and the mapping or redirect for /docs/latest/.
  • Do not modify zeppelin-site, historical documentation snapshots, or publication branches unless the user explicitly includes that work.

ASF Website Policy

  • Follow the ASF project website policy at https://privacy.apache.org/policies/website-policy.html and the Infra CSP guidance at https://infra.apache.org/csp.html.
  • Do not add Google Analytics or any other third-party analytics, tracker, tracking pixel, advertising tag, or external monitoring script.
  • Do not load JavaScript, CSS, fonts, images, or other assets from non-ASF domains. Host an asset in this repository when its license permits, or use a normal external link instead of embedding it.
  • Third-party embeds require the consent and DPA handling described by the ASF policy. Prefer a direct link unless the task explicitly includes an approved consent flow.
  • The production layout uses the ASF-hosted Matomo instance provisioned for Apache Zeppelin as site ID 69. Do not replace it with another analytics service or change its endpoint without Privacy team approval.

Verification

For every documentation change:

  1. Run the Docker publication build above from docs/.

  2. Confirm _site/index.html and the generated file for each changed page exist.

  3. Check generated navigation, links, images, and code blocks for the affected pages.

  4. Confirm generated URLs use the configured /docs/<version>/ prefix.

  5. Check the generated site for external trackers and embedded resources:

    docker run --rm \
  -v "$PWD:/docs:ro" \
  -w /docs \
  ruby:4.0.6 \
  ruby check_external_resources.rb _site

  6. Run git status --short and keep _site/ and incidental dependency changes out of the commit.

For navigation, layout, CSS, or JavaScript changes, also run the preview server and inspect the affected pages at desktop and narrow viewport widths.