Repository Guidelines

Project Structure & Module Organization

  • Primary Quarto pages sit in the repo root (index.qmd, about.qmd).
  • Published articles live in posts/<slug>/index.qmd; keep slugs lower-case, Spanish-friendly, and hyphen-separated to match existing URLs.
  • Drafts that should not ship belong in _drafts/, where each topic has its own folder for staging assets.
  • Static styling resides in styles.css; avoid editing files under _site/, which is regenerated by Quarto.
  • Legacy migration helpers (migration.py, migration2.py, migration_drafts.py) transform prior content—run them only when backfilling posts.

Build, Test, and Development Commands

  • make build (default) runs quarto render . and refreshes _site/.
  • make preview serves the site at http://127.0.0.1:4200 with live reload; interrupt with Ctrl+C when finished.
  • make check calls quarto check project to verify tools, extensions, and metadata.
  • make clean and make clean-cache clear build artefacts; use before troubleshooting stubborn render glitches.
  • make deploy and make deploy-preview push to Firebase Hosting once firebase.json is configured.

Coding Style & Naming Conventions

Quarto markdown uses fenced code blocks with explicit language tags (```r, ```python). Keep YAML front matter indented two spaces, list keys in English, and prefer camelCase for short code snippets. Reference local assets with relative paths and drop images next to the article that uses them. CSS additions go in styles.css, grouped by page component.

Testing Guidelines

Run make check before opening a pull request, then make build to confirm the site renders without warnings. Review the generated _site/ output in a browser to spot layout regressions. When altering scripts in /migration*.py, add a quick smoke execution against a single post to ensure the CLI still runs.

Commit & Pull Request Guidelines

Commits are short, present-tense summaries (e.g., gaus markov with image). Bundle related content edits together, but keep tooling updates isolated. Pull requests should explain the change scope, list affected posts, and attach preview URLs or screenshots when UI shifts are involved. Link tracking issues and flag any follow-up tasks in closing comments.

Deployment Notes

Firebase Hosting expects _site/ as the public directory (firebase.json). Authenticate with firebase login locally before the first deploy, and prefer make deploy-preview CHANNEL=feature-xyz for review environments that expire automatically.