mirror of
https://github.com/rjNemo/vf-site
synced 2026-06-11 03:26:39 +00:00
57 lines
2.3 KiB
Markdown
57 lines
2.3 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Modules
|
||
|
||
- `lib/`: static site generator code — `main.py` (entry point), `config.py`, `engine.py`.
|
||
- `pages/`: Jinja templates; layouts live in `pages/layouts/`.
|
||
- `data/`: page data in TOML; file name must match the template
|
||
(e.g., `index.toml` → `index.html`).
|
||
- `assets/`: static files copied as‑is (`css/`, `js/`, `images/`, `webfonts/`).
|
||
- `dist/`: build output (generated, can be deleted/rebuilt).
|
||
- `config.toml`: required; at minimum `name = "VillaFleurie"`.
|
||
|
||
## Build, Test, and Development
|
||
|
||
- `make build`: renders templates into `dist/` (`pipenv run python -m lib.main`).
|
||
- `make run`: builds then serves `dist/` via `http.server`.
|
||
- `make lint`: format (`black`), lint/fix (`ruff`), and type‑check (`mypy`).
|
||
- Direct run: `pipenv run python -m lib.main`.
|
||
- Setup: `pipenv install --dev` (Python 3.11).
|
||
|
||
## Coding Style & Naming
|
||
|
||
- Python: formatted by `black` (120 cols), imports via `isort` (black profile),
|
||
linted by `ruff`; type hints required (`mypy` with `disallow_untyped_defs`).
|
||
- Templates: Jinja; use inheritance with `pages/layouts/`. Prefer kebab‑case
|
||
filenames (e.g., `t3-azur.html`).
|
||
- Data files: TOML mirroring template names (e.g., `t3-azur.toml`). Keep keys lower_snake_case.
|
||
- Modules: snake_case for Python files and identifiers.
|
||
|
||
## Testing Guidelines
|
||
|
||
- No formal test suite. Validate changes by:
|
||
- Running `make lint` and fixing all issues.
|
||
- Building with `make build` and visually checking pages in `dist/` (`make run`).
|
||
- Verifying the correct data file is picked up for each template.
|
||
|
||
## Commit & Pull Requests
|
||
|
||
- Use Conventional Commits (seen in history):
|
||
- Examples: `refactor(html): modernize header markup`,
|
||
`feat(engine): add file watching`.
|
||
- PRs must:
|
||
- Pass `make lint` and build cleanly.
|
||
- Include a clear description, linked issues, and affected pages/files.
|
||
- Add screenshots of visual changes (before/after) where relevant.
|
||
- Stay focused and small; avoid mixed concerns.
|
||
|
||
## Revamp Spec & Branch
|
||
|
||
- Active branch: `revamp/website-spec`.
|
||
- Source of truth: `docs/spec/website-revamp-spec.md` (keep updated in PRs).
|
||
- Align changes to the agreed sitemap and CTAs defined in the spec.
|
||
|
||
## Configuration Tips
|
||
|
||
- Ensure `config.toml` exists at repo root; build fails without it.
|
||
- Do not commit generated `dist/` output.
|