Promising Beer - Project Guide #

This is Promising (promisingbeer.com), a non-alcoholic beer review site by Sam Brown. Built with Eleventy (11ty) and deployed as a static site.

Site Purpose #

Curating the best non-alcoholic beers for the sober curious. Reviews use a modified Robert Parker 100-point scoring system.

Tech Stack #

Review File Conventions #

Location and naming #

Frontmatter fields #

Every review requires this YAML frontmatter:

---
title: Beer Name Here          # Just the beer name, not the brewery. Exception: when the brewery name is part of the product's branded name (e.g. "Budweiser Zero", "Heineken 0.0", "Guinness Zero"), include it in the title.
date: YYYY-MM-DD               # Publication date
score: 74                      # Integer, 50-100 (see scoring below)
style: Hazy IPA                # Beer style
container: can                 # Optional: can (default), tall-can, or bottle. Used to normalize image scale on the /beers/ listing.
alcohol: 0.5%                  # ABV as percentage string. Use the ACTUAL ABV, not the marketed figure. Products branded "0.0" or "Zero" often still contain up to 0.5% by volume — record the real number.
calories: 98                   # Integer
lowsugar: Yes                  # Yes, No, or leave empty if unknown
glutenfree: No                 # Yes, No, or leave empty if unknown
brewery: Samuel Adams          # Brewery name
brewery_url: https://...       # Brewery website
origin: Boston, Massachusetts  # City/region, Country or State
img_beer: /img/beers/promising-brewery-beer-name.jpg
img_asset: /img/photos/brewery-beer-name.jpg
color: "#B5232F"               # Hex color representing the beer/brand
tags:
  - style tag                  # e.g. hazyipa, ipa, paleale, lager
  - brewery tag                # e.g. samueladams (no spaces/hyphens)
  - location tags              # e.g. boston, massachusetts, usa
layout: layouts/review.njk
featured_post: false           # Optional, omit or set true/false for homepage feature
featured_quote: ...            # Optional, a pull quote for featured reviews (used with featured_post: true)
---

Image paths #

Tags #

Tags are lowercase with no spaces or hyphens. Beer style first, then brewery name (as a single concatenated word, e.g. "otherhalfbrewing", "samueladams", "sierranevada"), then location tags if applicable.

Scoring System #

Sam's Writing Style #

Structure #

Every review is exactly three paragraphs. No more, no less.

  1. Brewery backstory: Who makes this beer, where they're from, a brief history or notable fact about the brewery. Sets context for the reader.
  2. Brewing details: How the beer is made, key ingredients, hop varieties, IBU, the brewing/fermentation process. Technical but accessible.
  3. Personal verdict: Sam's tasting experience, what stood out (good or bad), and a closing recommendation or warning. This is where the score lives in spirit.

Tone and voice #

Formatting rules #

Closing patterns #

Reviews almost always end with a direct recommendation or assessment aimed at the reader:

Things to avoid #

Site Architecture #

Layouts (in _includes/layouts/) #

Key templates (root level) #

Data files (_data/) #

Static files #

Eleventy config (.eleventy.js) #

Typography #

All visual type is expressed through a small set of .type-* classes defined in css/base.scss. Element-level h1–h4 are reset to margin: 0 and inherit sizing — they never carry visual treatment on their own. Pick semantic markup (<h2> if it's a heading, <p> if it's text, <dt> if it's a definition term) and add a class for visuals.

Class Size Treatment Use for
.type-display 96px (64px mobile) Display sans, weight 800, line-height 100% Score numerals, marquee tiles
.type-title 32px (24px mobile) Sans, weight 700, line-height 100% Card titles, page titles
.type-subtitle 24px Sans, weight 700, line-height 100% Smaller card titles
.type-body 24px (18px mobile) Sans, line-height 125% Paragraph copy (also the default <p> style)
.type-label 18px Sans, normal weight, dim Inline metadata (stats labels, brewery line, ABV, date, single-page subtitles)
.type-section-label 18px Sans, normal weight, dim, 16px bottom margin Section kickers introducing a block ("Featured review", "Recently reviewed", "Latest news")
.type-eyebrow 14px Sans, bold, uppercase, tracked, dim, 16px bottom margin Tiny tracked section kicker ("Breweries I've reviewed")
.type-caption 14px Sans Fine print

When you can't add a class — markdown-generated headings (## in editorial pages becomes a raw <h2>) — style them with a page-scoped rule (e.g. .single-content h2, .faq-page .single-content h2). These rules live alongside the page's other styles and override the empty element-level reset.

Don't introduce new font-size declarations inside per-page stylesheets unless the case is genuinely outside the system. If you find yourself wanting a new type style, add it to base.scss and document it here.

SEO and structured data #

All SEO markup lives in base.njk <head>. When modifying SEO:

Content pages #

Workflow for New Reviews #

  1. Always ask Sam clarifying questions about his tasting experience before writing
  2. Research the beer and brewery for accurate facts (ABV, calories, hops, IBU, origin, brewing process, awards)
  3. Also research the beer's history for storytelling moments worth including: launch stories, recalls, relaunches, notable awards, acquisitions, controversies, or cultural moments. These add texture to the brewery backstory paragraph beyond dry facts.
  4. Create the file in /reviews/ with complete frontmatter
  5. Write the three-paragraph review body matching the style guide above
  6. Sam will need to add photos separately (img_beer, img_asset)
  7. The review will automatically appear in llms-full.txt on next build