~ajhalili2006's personal website, built with Zensical (successor of Material for Mkdocs) [old repo name got bugged while attempting to do manual knot migration via repo deletion]
andreijiroh.dev
andreijiroh.dev
zensical
mkdocs-material
website
1# GitHub Copilot / AI agent instructions
2
3Purpose: help an AI coding agent be immediately productive in this repository.
4
5- Big picture
6 - Static site built with MkDocs + Material theme. Sources live in `markdown/`; generated site is written to `public/` ([mkdocs.yml](mkdocs.yml)).
7 - Theme customizations and build hooks are in `overrides/` (Python hooks + theme assets).
8 - A parallel Gemini site lives in `gmi/` (different format, separate publishing flow).
9 - Cloudflare Pages / Workers integration: see `wrangler.jsonc` (publishes assets from `public/`).
10
11- Key workflows (concrete commands)
12 - Install dependencies (preferred): `pipenv install` (or `pip install -r requirements.txt`). See [Pipfile](Pipfile) and [requirements.txt](requirements.txt).
13 - Local preview: `mkdocs serve --watch overrides --watch-theme --livereload` or `pipenv run dev` (see `Pipfile` scripts and [mkdocs.yml](mkdocs.yml)).
14 - 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.
15 - Cloudflare deploy (manual): `npm run deploy` -> `wrangler deploy` (see `package.json` and [wrangler.jsonc](wrangler.jsonc)). CI deploy logic uses `npx wrangler pages publish` in `bin/deploy.sh` when running under CI.
16 - CI: deployments happen via GitLab CI; do not rely on a repository-local Docker CI image.
17
18- Project-specific conventions & patterns
19 - Content separation: author-managed Markdown in `markdown/` is canonical. Do not edit `public/` — it is generated.
20 - Theme overrides and custom assets live in `overrides/`; changes there affect build behavior and the site theme.
21 - 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.
22 - Python environment targets Python 3.13 (see `Pipfile`). The repo commonly uses `pipenv` and a `.venv` pattern in local scripts (`bin/localdev.sh`).
23 - CI: deployments happen via GitLab CI and `bin/deploy.sh` (see `wrangler.jsonc` for Cloudflare Pages configuration).
24
25- Integration points & external dependencies
26 - Cloudflare Pages / Workers via `wrangler`/`wrangler.jsonc` (assets directory: `./public`).
27 - CI builds run on GitLab. Avoid referencing the `docker/` folder — it may be moved to a separate repo.
28 - `npm` is used only for `wrangler` dev/deploy and Docker convenience scripts (`package.json`).
29
30- Helpful files to inspect
31 - Repository README: [README.md](README.md)
32 - MkDocs config: [mkdocs.yml](mkdocs.yml)
33 - Build scripts: [build.sh](build.sh) and [bin/build.sh](bin/build.sh)
34 - CI/deploy: [bin/deploy.sh](bin/deploy.sh) and [wrangler.jsonc](wrangler.jsonc)
35 - Python deps: [Pipfile](Pipfile) and [requirements.txt](requirements.txt)
36 -
37
38- What NOT to do
39 - Do not edit generated files under `public/` directly — change sources in `markdown/` or `overrides/`.
40 - Avoid changing `site_dir` or `assets` layout without verifying `wrangler.jsonc` and `bin/deploy.sh` updates.
41
42- If you need clarification
43 - Ask the maintainer which mirror/CI (GitLab primary) you want to target before modifying CI configs.
44
45- Next steps
46 - If you want, I can expand the CI section with example GitLab job snippets or add examples for contributing patches.
47
48- Commit attribution
49 - Adopt the `Assisted-by` commit trailer for AI-assisted changes to comply with attribution policies.
50 - Required trailer format (commit footer):
51
52```
53Assisted-by: <Model Name> via <Tool Name>
54```
55
56 - Example:
57
58```
59Assisted-by: GLM 4.6 via Claude Code
60```
61
62 - Repository also requires Linux DCO sign-off for patches. Ensure commits include `Signed-off-by:` lines in the footer alongside `Assisted-by:` when applicable.
63
64If any section is unclear or you want deeper examples (e.g., contributing workflow, CI job templates), tell me which area to expand.
65
66- Example: GitLab CI snippet
67 - Minimal job that builds the site and publishes to Cloudflare Pages using `wrangler`.
68
69```yaml
70stages:
71 - build
72 - deploy
73
74build_site:
75 stage: build
76 image: node:20-bullseye
77 script:
78 - pip install pipenv
79 - pipenv install --deploy --ignore-pipfile
80 - pipenv run build
81 artifacts:
82 paths:
83 - public/
84
85publish_pages:
86 stage: deploy
87 image: node:20-bullseye
88 dependencies:
89 - build_site
90 script:
91 - npm install -g wrangler
92 - npx wrangler pages publish public --project-name "$CF_PAGES_PROJECT_NAME" --branch "$CI_COMMIT_BRANCH"
93 only:
94 - main
95```
96
97 - 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.