~ajhalili2006's personal website, built with Zensical (successor of Material for Mkdocs)
andreijiroh.dev
mkdocs-material
zensical
website
cf-pages
docs: add GitHub Copilot custom instructions
Assisted-by: GPT-5 mini via GitHub Copilot Chat for VS Code
Signed-off-by: Andrei Jiroh Halili <ajhalili2006@andreijiroh.dev>
Andrei Jiroh Halili
(Dec 6, 2025, 2:43 AM UTC)
65339df6
eb39ab2f
+97
+97
.github/copilot-instructions.md
+97
.github/copilot-instructions.md
···
1
+
# GitHub Copilot / AI agent instructions
2
+
3
+
Purpose: 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
+
```
53
+
Assisted-by: <Model Name> via <Tool Name>
54
+
```
55
+
56
+
- Example:
57
+
58
+
```
59
+
Assisted-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
+
64
+
If 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
70
+
stages:
71
+
- build
72
+
- deploy
73
+
74
+
build_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
+
85
+
publish_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.