How cot-rs/cot-site works
Project type and purpose
• Cot-site is a Rust-based static/dynamic website generator for the Cot web framework’s documentation.
• It reads Markdown “guides” and “md-pages”, processes them via Rust macros and templates, then serves them over HTTP (or builds static assets for Nginx).
File structure
• Top-level “src/” contains the Rust web-server code (main.rs, guides.rs, MD pages).
• “cot-site-common/” and “cot-site-macros/” are internal libraries:
• common: shared logic for loading MD pages, serving paths
• macros: compile-time MD→HTML embedding
• “templates/” holds all HTML templates (.html).
• “static/” houses images, JS, and webmanifest.
• “scss/” & “syntax-highlighting/” feed SCSS and syntax themes into the front end.
• “nginx/” defines a Dockerized static-file server.
• Dockerfiles, docker-compose, CI YAMLs show containerization and CI pipeline.
• “scripts/” includes helper scripts (e.g. favicons).
Extract insights from the README
• No external services (DB/etc).
• Dev flow: cargo run to launch the Rust HTTP server.
• Nightly + features for live MD macro reload.
• Optionally use “bacon” for live-reload.
Main components
a. Developer environment
• Rust toolchain (stable + nightly)
• bacon (optional live-reload)
• Docker & Docker-Compose (for production build)
b. Build pipeline
• cot-site-macros → procedural macro transforms .md → Rust functions
• cot-site-common → MD page loader & shared utilities
• scss compiler → CSS assets
• syntax-highlighting assets → JS/CSS
• Rust compiler (build.rs, Cargo) → binary
c. Runtime / Server
• Rust HTTP server (serves dynamic docs)
• Template engine renders HTML
• Static assets (CSS/JS/images) served from memory or disk
d. Deployment
• Docker container running the Rust binary behind an Nginx reverse proxy
• Optional separate Nginx container for pure static hosting
e. External tools/services
• GitHub Actions (CI for Rust build & Docker images)
• Docker Hub (or registry)
Relationships & data-flow
• Developer → triggers build (Cargo or Docker-Compose)
• MD files + macros + templates → compile → Rust binary
• SCSS & syntax themes → compiled static assets
• At runtime: HTTP request → Rust server → template + HTML → HTTP response
• Browser ← served HTML + CSS/JS ← Nginx or Rust server
• CI pipeline → validates build → publishes Docker image
Architectural patterns & design principles
• Monolithic Rust application using modular internal crates
• Compile-time code generation (procedural macros) for MD processing
• Separation of concerns:
• Content (Markdown)
• Presentation (Templates + SCSS)
• Logic (Rust server + common lib)
• Infrastructure (Docker, Nginx)
• Dev/Prod parity via Docker-Compose
Next steps for the principal software engineer
• Out each node/component as above.
• Related items (e.g., internal crates vs external tools).
• Sketch arrowed flows, validate with team.
• Iterate: add infrastructure (Docker-Compose networks, volumes) if needed.