This is an automated email from the ASF dual-hosted git repository. benweidig pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/tapestry-5-site-builder.git
commit 1709a60fd03f22edd747a05f92fe7c0ad6ffc319 Author: Ben Weidig <[email protected]> AuthorDate: Sat Aug 29 12:06:42 2026 +0200 docs(readme): document local previews and how to trigger a build Two things that are not discoverable from the repo itself: previewing an unpushed content checkout with -PlocalPlaybook, and the fact that content pushes to tapestry-5-site never start a build because the Jenkinsfile lives here. --- README.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f68a2b9..136b7e2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,56 @@ # tapestry-5-site-builder.git This repo contains the site configuration and the build logic. +The content itself lives in [tapestry-5-site.git](https://gitbox.apache.org/repos/asf/tapestry-5-site.git), one branch per version. -Leveraging the Gradle Antora Plugin, simply run `./gradlew antora` to have the site generated. +Leveraging the Gradle Antora Plugin, simply run `./gradlew antora` to have the site generated into `build/site`. +## Building + +```sh +./gradlew antora +``` + +This fetches the content from gitbox, so it renders what is **pushed**, not what is in your local checkout. + +### Previewing local changes + +To render a sibling checkout of `tapestry-5-site` instead: + +```sh +./gradlew antora -PlocalPlaybook +open build/site/index.html +``` + +This uses `antora-playbook-local.yml`, which expects `tapestry-5-site` next to this repo: + +```text +code/ +├── tapestry-5-site/ +└── tapestry-5-site-builder/ +``` + +Antora reads the **committed branches** of that checkout, never the working tree, so commit before building. +Editing a page and rebuilding shows no change until the edit is committed. + +## Publishing + +The site is built and staged by Jenkins, defined in the `Jenkinsfile`: + +1. `./gradlew antora` generates the site, and `.htaccess` is copied into the output. +2. On the `main` branch only, the result is committed to the `asf-staging` branch and pushed. +3. ASF infrastructure serves that branch at <https://tapestry.staged.apache.org/>. + +The `asf-staging` branch holds **generated output**, not source. +Jenkins wipes everything but `.git` and `.asf.yaml` on each run, so never merge into it or commit to it by hand. + +### Triggering a build + +The Jenkins job is at +<https://ci-builds.apache.org/job/Tapestry/job/tapestry-5-site-builder/>. + +It builds on pushes to **this** repo only. +Pushing content to `tapestry-5-site` does **not** start a build, because that repo has no `Jenkinsfile`. + +So after changing content, go to the job and use **Build Now** to publish it. +The same applies to a new version branch in the content repo.
