---
name: jekyll-site-conventions
description: Conventions and hard rules for the cloudfrontsgroup.org Jekyll site. Load before editing HTML, Liquid, layouts, includes, _config.yml, CSS, or blog posts in this repository.
---
# cloudfrontsgroup.org — site conventions

## What this site is now
- A Jekyll site. GitHub Pages builds it with the `github-pages` gem (Jekyll 3.10); local preview
  uses Jekyll 4.4 (`bundle exec jekyll serve`). Keep templates compatible with both and use only
  the plugins in `_config.yml` (`jekyll-feed`, `jekyll-sitemap`).
- Root pages (`index.html`, `about-us.html`, ...) are thin files: YAML front matter (`title`,
  `description`, `active`, optional `canonical`, `schema_desc`, `section`) plus the page body.
  They render through `_layouts/default.html`, which includes `_includes/head.html`,
  `header.html` and `footer.html`. Navigation comes from `_data/nav.yml` and `_data/footer_nav.yml`.
- Blog posts are Markdown in `_posts/`, published at `/blog/<slug>.html` through
  `_layouts/post.html` with `_includes/share.html`. Front-matter defaults for posts live in
  `_config.yml`. Authoring guide: `docs/blog-authoring.md`.
- Site-wide values (phone, emails, social links, brand tokens, schema description) live in
  `_config.yml` and are read by the includes; do not hard-code them in templates.
- The legacy Python build (`_build/build.py`, `_pages/`, `_partials/`) was removed on 2026-10-30
  after an output-parity check. `scripts/compare_build.py` remains for regression checks.

## Layout
```
_config.yml              site values, brand tokens, plugins, front-matter defaults
_data/nav.yml            header navigation (top-level `key` drives the active state)
_data/footer_nav.yml     footer quick links
_layouts/default.html    <html> shell: head + header + {{ content }} + footer
_layouts/post.html       blog post: hero, body, share bar, prev/next, CTA
_includes/head.html      title, meta, canonical, Open Graph / Twitter, JSON-LD
_includes/header.html    skip link, wordmark, nav from site.data.nav
_includes/footer.html    footer, back-to-top, scripts
_includes/share.html     static share links (X, Facebook, LinkedIn, email, copy)
_posts/*.md              blog posts
blog.html                blog index
style.css                source stylesheet; style.min.css is generated by scripts/minify_css.py
```

## Rules
1. **Parity on refactors.** When changing layouts or includes, snapshot first
   (`python3 scripts/compare_build.py snapshot`), rebuild, then
   `python3 scripts/compare_build.py compare`; every unexpected diff must be explained.
2. Posts link back to the site with `../` (they live under `/blog/`); root pages use plain
   relative links (`contact.html`). The `rp` variable in templates carries this prefix.
3. Do not add anything that needs a backend, API key, database or analytics provider.
4. Keep `.nojekyll` absent: GitHub Pages must run Jekyll for this site to publish.
5. HTML hygiene: one `class` attribute per element, valid nesting, `alt` on every `<img>`,
   `aria-label` on icon-only buttons, Lucide icons via `data-lucide`.
6. Styles stay in `style.css`; after editing run `python3 scripts/minify_css.py`.
7. New site-wide values go in `_config.yml`; new nav entries go in `_data/nav.yml`.
8. Never invent testimonials, client logos, statistics or awards in copy.