GitHub Copilot / AI agent instructions#

Purpose: help an AI coding agent be immediately productive in this repository.

• Big picture

  • Static site built with MkDocs + Material theme. Sources live in markdown/; generated site is written to public/ (mkdocs.yml).
  • Theme customizations and build hooks are in overrides/ (Python hooks + theme assets).
  • A parallel Gemini site lives in gmi/ (different format, separate publishing flow).
  • Cloudflare Pages / Workers integration: see wrangler.jsonc (publishes assets from public/).

• Key workflows (concrete commands)

  • Install dependencies (preferred): pipenv install (or pip install -r requirements.txt). See Pipfile and requirements.txt.
  • Local preview: mkdocs serve --watch overrides --watch-theme --livereload or pipenv run dev (see Pipfile scripts and mkdocs.yml).
  • Build site: pipenv run build or pipenv run build -f mkdocs.readthedocs.yml (build targets in Pipfile and build.sh). build.sh copies favicon into public/ after build.
  • Cloudflare deploy (manual): npm run deploy -> wrangler deploy (see package.json and wrangler.jsonc). CI deploy logic uses npx wrangler pages publish in bin/deploy.sh when running under CI.
  • CI: deployments happen via GitLab CI; do not rely on a repository-local Docker CI image.

• Project-specific conventions & patterns

  • Content separation: author-managed Markdown in markdown/ is canonical. Do not edit public/ — it is generated.
  • Theme overrides and custom assets live in overrides/; changes there affect build behavior and the site theme.
  • The build copies assets/images/favicon.png to public/favicon.ico after building (see build.sh and bin/build.sh). Keep favicon at that path.
  • Python environment targets Python 3.13 (see Pipfile). The repo commonly uses pipenv and a .venv pattern in local scripts (bin/localdev.sh).
  • CI: deployments happen via GitLab CI and bin/deploy.sh (see wrangler.jsonc for Cloudflare Pages configuration).

• Integration points & external dependencies

  • Cloudflare Pages / Workers via wrangler/wrangler.jsonc (assets directory: ./public).
  • CI builds run on GitLab. Avoid referencing the docker/ folder — it may be moved to a separate repo.
  • npm is used only for wrangler dev/deploy and Docker convenience scripts (package.json).

• Helpful files to inspect

  • Repository README: README.md
  • MkDocs config: mkdocs.yml
  • Build scripts: build.sh and bin/build.sh
  • CI/deploy: bin/deploy.sh and wrangler.jsonc
  • Python deps: Pipfile and requirements.txt

• What NOT to do

  • Do not edit generated files under public/ directly — change sources in markdown/ or overrides/.
  • Avoid changing site_dir or assets layout without verifying wrangler.jsonc and bin/deploy.sh updates.

• If you need clarification

  • Ask the maintainer which mirror/CI (GitLab primary) you want to target before modifying CI configs.

• Next steps

  • If you want, I can expand the CI section with example GitLab job snippets or add examples for contributing patches.

• Commit attribution

  • Adopt the Assisted-by commit trailer for AI-assisted changes to comply with attribution policies.
  • Required trailer format (commit footer):

Assisted-by: <Model Name> via <Tool Name>

• Example:

Assisted-by: GLM 4.6 via Claude Code

• Repository also requires Linux DCO sign-off for patches. Ensure commits include Signed-off-by: lines in the footer alongside Assisted-by: when applicable.

If any section is unclear or you want deeper examples (e.g., contributing workflow, CI job templates), tell me which area to expand.

• Example: GitLab CI snippet
  • Minimal job that builds the site and publishes to Cloudflare Pages using wrangler.

stages:
  - build
  - deploy

build_site:
  stage: build
  image: node:20-bullseye
  script:
    - pip install pipenv
    - pipenv install --deploy --ignore-pipfile
    - pipenv run build
  artifacts:
    paths:
      - public/

publish_pages:
  stage: deploy
  image: node:20-bullseye
  dependencies:
    - build_site
  script:
    - npm install -g wrangler
    - npx wrangler pages publish public --project-name "$CF_PAGES_PROJECT_NAME" --branch "$CI_COMMIT_BRANCH"
  only:
    - main

• Notes: set CF_PAGES_PROJECT_NAME in CI variables; the repo's bin/deploy.sh also contains an example npx wrangler pages publish invocation used by CI.