Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (51 loc) · 3.09 KB

AGENTS.md

File metadata and controls

67 lines (51 loc) · 3.09 KB

Repository Guidelines

Project Structure & Module Organization

This repository is a Zensical-powered static site. Author English content in content/en/ and Spanish content in content/es/, keeping the same page structure across both languages. Language-local assets live in content/en/assets/ and content/es/assets/. Site configuration and navigation live in zensical.toml and zensical.es.toml; add new pages there so they appear in the menu. Tooling is defined in pyproject.toml, uv.lock, and Justfile. CI workflows live in .github/workflows/, and repository-wide lint/security settings live under .config/.

Root-level working documents that are not meant to be published, such as CV drafts or session notes, should stay outside content/, should not be added to the Zensical configs, and should be kept gitignored when they are for local/private use only.

Build, Test, and Development Commands

Use just as the main entry point:

  • just sync: install or refresh dependencies with uv.
  • just serve: start the local dev server at http://127.0.0.1:8000.
  • just build: generate the static site into site/.
  • just lint: run all pre-commit checks across the repo.
  • just links: optional outbound link validation with Lychee.
  • just audit: scan Python dependencies for known vulnerabilities.

Run just build and just lint before opening a PR.

Coding Style & Naming Conventions

Follow .editorconfig: UTF-8, LF endings, final newline, and spaces for indentation. Use 2 spaces by default and 4 spaces in Python files. Keep Markdown filenames descriptive and lowercase with hyphens, for example cloud-data.md or security-quality.md. Prefer concise Markdown with clear headings; let pre-commit manage whitespace and Markdown formatting. Keep reusable styling in the language-local assets/stylesheets/extra.css files instead of scattering one-off presentation changes.

Testing Guidelines

There is no dedicated unit-test suite in this repository. Validation is content- and build-focused: run just build, just lint, and, when editing links or adding external references, just links. Preview significant content or styling changes locally with just serve, and verify any new page is linked in zensical.toml.

Commit & Pull Request Guidelines

Commit messages follow Conventional Commits and are enforced by Commitizen (feat:, fix:, docs:, chore:). Use just commit for the guided flow when possible. Keep PRs focused and complete the existing template: summarize the change, mark the change type, list validation performed, and link related issues. Include screenshots for changes that alter rendered pages or styling.

Git publishing operations are user-managed. Do not run git push, create or switch branches, or perform release/publication steps unless the user asks explicitly; branch strategy and remote updates are handled manually by the repository owner.

Security & Configuration Tips

Do not commit secrets; detect-secrets runs in pre-commit using .config/.secrets.baseline. For dependency or workflow changes, keep uv.lock in sync with pyproject.toml.