AGENTS.md — Apache Solr Website

This file helps AI agents understand the repository structure and workflow.

What this repo is

Static website for solr.apache.org, built with Pelican (Python static site generator). Content is written in Markdown. The build runs inside Docker to ensure a reproducible environment.

How to build and preview

./build.sh -l    # build and serve with live reload at http://localhost:8000
./build.sh       # one-shot build into output/
./build.sh -h    # show all options

Docker must be installed. The script auto-builds the image if missing, and auto-rebuilds it if requirements.txt is newer than the cached image.

Key files and directories

Path	Purpose
`pelicanconf.py`	Pelican configuration; defines `SOLR_LATEST_RELEASE` and other site-wide variables
`content/pages/`	All site pages as Markdown files
`content/pages/blogposts/`	Blog posts
`themes/solr/templates/`	Jinja2 HTML templates
`themes/solr/static/`	CSS, JS, images
`plugins/`	Local Pelican plugins (Python)
`requirements.in`	Direct Python dependencies (human-editable)
`requirements.txt`	Hash-verified lockfile generated from `requirements.in` — do not edit by hand
`Dockerfile`	Base image pinned by digest; Dependabot tracks it
`.github/dependabot.yml`	Dependabot config for pip, docker, and github-actions ecosystems

Updating dependencies

Edit requirements.in, then regenerate the lockfile and rebuild the image:

./build.sh --lock -b

Or in two steps:

./build.sh --lock   # regenerates requirements.txt inside Docker
./build.sh -b       # rebuilds the Docker image

Updating Solr release versions

Edit pelicanconf.py and bump SOLR_LATEST_RELEASE, SOLR_LATEST_RELEASE_DATE, and SOLR_PREVIOUS_MAJOR_RELEASE. These variables propagate throughout the theme automatically.

Templates and pages

Templates use Jinja2. Most pages use the base.html template.
A page can specify a custom template with Template: my-template in its Markdown front matter.
The jinja2content plugin allows Jinja2 expressions directly inside Markdown pages.

Branch and deploy model

Branch	Purpose
`main`	Staging — auto-deployed to solr.staged.apache.org
`production`	Live site — merge `main` → `production` to publish

Never commit directly to production. Always go through main (and a PR).

CI

Pull requests: Pelican build only (no publish), defined in .github/workflows/pr-build-pelican.yml
Push to main/production: full build + publish, defined in .github/workflows/build-pelican.yml
All GitHub Actions refs are pinned to commit SHAs and tracked by Dependabot.