|
| 1 | +# C++ Alliance Website |
| 2 | + |
| 3 | +Source code for [cppalliance.org](https://cppalliance.org), The C++ Alliance’s public-facing site. It is a classic Jekyll 3.8 project that publishes a fully static site through GitHub Pages. |
| 4 | + |
| 5 | +## Typical Workflow |
| 6 | + |
| 7 | +```bash |
| 8 | +bundle install |
| 9 | +bundle exec jekyll serve --livereload |
| 10 | +``` |
| 11 | + |
| 12 | +1. Install Ruby dependencies via Bundler. |
| 13 | +2. Iterate locally with `bundle exec jekyll serve --livereload`; it compiles Sass, renders Markdown/HTML, and writes to `_site/`. |
| 14 | +3. Edit content in `_posts/`, `people/`, and page files; adjust styling inside `_sass`; place supporting media in the relevant asset directories. |
| 15 | +4. Commit only source files. `_site/` is build output and should remain untracked. |
| 16 | + |
| 17 | +## Authoring Blog Posts |
| 18 | + |
| 19 | +1. Name files `YYYY-MM-DD-title.md` and place them in `_posts/`. |
| 20 | +2. Use front matter similar to (or use other posts as templates): |
| 21 | + ```yaml |
| 22 | + --- |
| 23 | + layout: post |
| 24 | + nav-class: dark |
| 25 | + categories: company, vinnie # include the author’s id |
| 26 | + title: Something Worth Reading |
| 27 | + author-id: vinnie # maps to people/vinnie.html |
| 28 | + hero-image: 2024-01-01-title.png # optional; stored under images/posts/ |
| 29 | + large-image: /images/social-card.png # optional Twitter card override |
| 30 | + summary: Optional 160-character blurb for social cards |
| 31 | + --- |
| 32 | + ``` |
| 33 | +3. Provide `author-name` if there is no matching `people/<id>.html`. Otherwise the layout resolves the display name automatically. |
| 34 | +4. Store hero images under `images/posts/`; they appear in both the post header and the News index when present. |
| 35 | +5. `_layouts/post.html` compares the full `categories` array when building the “All posts by this author” list. Keep author ids consistent and avoid shuffling them between posts, or the archive may appear empty. |
| 36 | +6. When a post has many sections, drop `{% include post-toc.md title="Contents" %}` just below the intro. The include emits Kramdown’s `{:toc}` macro so the list stays synchronized with every heading automatically; omit the `title` param to fall back to “Table of Contents.” |
| 37 | +7. Write the body in Markdown/HTML, preview with `bundle exec jekyll serve --livereload`, and confirm the post surfaces on `/news` and the author’s bio page. The legacy [wiki guide](https://github.com/cppalliance/cppalliance.github.io/wiki/Posting-a-Blog) still applies, but this README is the canonical reference. |
| 38 | + |
| 39 | +## Architecture |
| 40 | + |
| 41 | +- `_config.yml` defines site metadata (title, description, contact email, social handles), Markdown settings (Kramdown + GFM), pagination defaults, Atom feed limits, Twitter card fallback, and plugin configuration (`jekyll-feed`, `jekyll-sitemap`, `jekyll-email-protect`, `jekyll-seo-tag`, `jekyll-paginate`). |
| 42 | +- `Gemfile` pins Jekyll `~> 3.8.3`, Minima `~> 2.0`, and the plugin bundle. Always run commands via `bundle exec` so these locked versions are honored. |
| 43 | +- `_layouts/default.html` supplies the HTML skeleton: Google Fonts, compiled CSS, SEO tags, navigation, footer, analytics (Plausible + Google Analytics), Atom feed discovery, and conditional Prism assets for posts. |
| 44 | +- `_site/` contains the generated output—never hand-edit it. `CNAME` keeps the Pages deployment bound to `cppalliance.org`. |
| 45 | +- `Project Operation Guide.adoc` documents high-level operational practices (onboarding, hiring models) and should be updated alongside code conventions when relevant. |
| 46 | + |
| 47 | +## Content Model |
| 48 | + |
| 49 | +- `index.html` composes Mission, Activities, Sponsors, Team, FAQ, News, and Contact sections. The IDs exposed there (`#mission`, `#team`, etc.) must stay aligned with the nav links inside `_layouts/default.html`. |
| 50 | +- Long-form subpages include `news/index.html` (paginate `_posts` with optional hero art), `slack/index.html` (community FAQ + acceptable-use policy), and `proposals.html` (funding-request guidance). |
| 51 | +- `_posts/*.md` house dated blog/news entries with `layout: post`. Each post must include the author’s id in `categories` so it flows into team pages. |
| 52 | +- `people/*.html` define team bios via front matter (`member-name`, `position`, `id`, contact links). Portraits live at `images/people/<id>.jpg` and are consumed by the `team` layout. |
| 53 | +- Static assets such as PDFs, videos, SVG illustrations, and hero artwork sit directly under `/pdf`, `/videos`, `/images`, etc., and are linked from the relevant pages. |
| 54 | + |
| 55 | +## Layouts & Includes |
| 56 | + |
| 57 | +- `_layouts/post.html` renders individual posts, handles hero images, resolves `author-id` into a display name, loads Prism assets, and generates an “All posts by this author” list. |
| 58 | +- `_layouts/team.html` renders member pages with the photo, title, social icon bar (`_includes/team-bio.html`), bio body, and the `_includes/team-blog.html` feed filtered by `site.categories[page.id]`. |
| 59 | +- `_includes/top-title.html` supplies the home hero; `contact.html` renders the “Connect” social grid; `favicon.html` injects favicon link tags; `paginator.html` drives numbered pagination; `team-bio.html` outputs gold icons for each contact field. |
| 60 | + |
| 61 | +## Default Layout Behavior |
| 62 | + |
| 63 | +- `page.nav-class` toggles nav styling (`transparent` for the homepage hero, `dark` elsewhere). Always set it on new pages. |
| 64 | +- Social metadata falls back to `site.title_image`. Posts can override via `page.image` or `page.large-image`, and supplying `page.summary` tightens the Twitter description. |
| 65 | +- Nav links are hardcoded to the homepage anchors plus a few static pages. Keep section IDs and link targets synchronized to avoid dead anchors, especially on mobile. |
| 66 | +- Plausible and Google Analytics scripts live exclusively in the default layout; no other template should add tracking snippets. |
| 67 | +- Prism CSS/JS only load when `page.layout == 'post'`. Reuse that layout (or the same condition) for any new syntax-highlighted content. |
| 68 | + |
| 69 | +## Styling |
| 70 | + |
| 71 | +- `css/style.scss` is the sole Sass entry point compiled by Jekyll into `css/style.css`. It imports partials in this order: |
| 72 | + - `_sass/base`: reset, tokens (`config.scss`), helper functions, typography, print styles. |
| 73 | + - `_sass/modules`: reusable components (cards, hero, navigation, layout grid, news list, Slack page, footer, social icons). |
| 74 | + - `_sass/pages`: page-specific layers (`homepage.scss`, `post.scss`, `team.scss`). `post_backup.scss` is retained for reference but not imported. |
| 75 | +- `css/prism.css` styles syntax-highlighted blocks inside posts and is only loaded when the layout requests it. |
| 76 | + |
| 77 | +## Scripts & Interactivity |
| 78 | + |
| 79 | +- `js/main.js` powers the responsive nav drawer: toggles the hamburger, locks body scroll when the menu is open, closes the drawer on resize, and auto-hides after tapping any `.nav-link-mobile` below 1024px width. |
| 80 | +- `js/prism.js` is a vendored PrismJS 1.20.0 build with C/C++ grammars and the `line-numbers`, `toolbar`, and `copy-to-clipboard` plugins. The default layout loads it for post pages only. |
| 81 | + |
| 82 | +## Key Pages & Sections |
| 83 | + |
| 84 | +- `news/index.html` uses `paginator.posts` (5 per page by default) and falls back to `site.posts` if pagination is disabled. Snippets come from `post.content | strip_html | truncate: 500`. |
| 85 | +- `slack/index.html` is the authoritative source for invite links, FAQs, acceptable-use policy, and resource links. Its markup ties directly into `_sass/modules/slack.scss`. |
| 86 | +- `proposals.html` describes the criteria for funding proposals and emails `louis@cppalliance.org` (encoded via `| encode_email`). |
| 87 | +- `people/*.html` rely on `page.id` matching the filename and portrait asset. The same id doubles as the key in `site.categories`. |
| 88 | +- `index.html` hardcodes the team card grid, pulls in the hero include, and reuses `contact.html`. Updating the team requires changes here plus the corresponding `people/*.html` entries and portrait assets. |
| 89 | + |
| 90 | +## Assets |
| 91 | + |
| 92 | +- Static media lives directly under `/images`, `/videos`, `/fonts`, `/pdf`, and `/news`. Social icons live in `images/icons/*.svg` and are referenced in both the nav and contact sections. |
| 93 | +- Blog hero art should live in `images/posts/`. People portraits must sit under `images/people/` using the person’s `id`. |
| 94 | +- Favicons (`favicon-*.png`, `safari-pinned-tab.svg`, `android-chrome-*.png`, etc.) and `CNAME` support the custom domain—update only when branding changes. |
| 95 | + |
| 96 | +## Maintenance Notes & Gotchas |
| 97 | + |
| 98 | +- Keep navigation anchor IDs synchronized with the hardcoded links in `_layouts/default.html`. If you rename `#mission`, update both the section ID and every nav link pointing to it. |
| 99 | +- `_includes/team-blog.html` expects `site.categories[page.id]` to exist. If a member page renders no posts, double-check the spelling of the author id in every post’s `categories`. |
| 100 | +- `_includes/paginator.html` references `site.data.ui-text[site.locale]` for labeling. Leaving these values unset falls back to “Previous/Next,” so only touch them if localization is intentional. |
| 101 | +- Encode email addresses with `| encode_email` for consistency (`contact.html`, `proposals.html`, people pages). |
| 102 | +- When creating new highlighted pages, either reuse `layout: post` or replicate its Prism loading behavior. |
| 103 | +- Never modify files under `_site/`; rebuild instead. |
0 commit comments