# Repository Guidelines ## Project Structure & Module Organization - `ghost-upload/`: Rust automation for Ghost CMS publishing. - `posts/`: Quarto posts with Julia/Python code per post directory. - `public/`: Quarto build output (generated by `quarto render`). - Root: Quarto config (`_quarto.yml`), shared assets, CI/CD, docs. ## Build, Test, and Development Commands - Rust (`ghost-upload/`): - Build: `cd ghost-upload && cargo build` - Run: `cd ghost-upload && cargo run` - Test: `cd ghost-upload && cargo test` (single: `cargo test `) - Lint: `cd ghost-upload && cargo clippy` - Format: `cd ghost-upload && cargo fmt` - Julia (root or `posts/*/`): - Packages: `julia -e "using Pkg; Pkg.instantiate()"` - Precompile: `julia -e "using Pkg; Pkg.precompile()"` - Run notebook/script: `julia .jl` - Quarto (docs/site): - Build site: `quarto render --to html --output-dir public` - Preview: `quarto preview` - Check: `quarto check` - Docker: `docker build -t projects .` then `docker run projects` ## Coding Style & Naming Conventions - Rust: `cargo fmt`; fix all `cargo clippy` warnings. Use `?` over `unwrap()`. Imports: std → external → local. Naming: snake_case (fn/vars), PascalCase (types). Public docs with `///`. - Julia: 4-space indent; spaces around operators; group `using` at top; snake_case; prefer pipelines `|>` for DataFrames; handle expected errors with try-catch. - Quarto: Include title/date in YAML; set `echo: false`, `warning: false` for clean outputs; descriptive figure captions and alt text. ## Testing Guidelines - Rust: Unit tests for core logic; add integration tests for API calls. Run with `cargo test`. Organize tests near code or in `tests/`. - Julia: Validate transformations and plots visually; keep scripts deterministic. - Quarto: Manually review rendered HTML for links, figures, and warnings. ## Commit & Pull Request Guidelines - Commits: Use clear, conventional messages (e.g., `feat:`, `fix:`, `docs:`). Scope small and focused. - PRs: Provide description, linked issues, steps to validate (commands), and screenshots of rendered docs when relevant. ## Security & Configuration - Environment variables: `kagi_api_key`, `admin_api_key`. Export locally (e.g., `export admin_api_key=...`); never commit secrets. - Dependencies: Keep minimal and up-to-date. Prefer configuration via env vars over hardcoded values. ## CI/CD & Deployment - GitLab CI builds Docker, renders Quarto to static hosting; Rust runs separately for content sync. Avoid pipeline changes unless necessary; include rationale in PRs if modified.