Content Editing Documentation

This guide covers the building blocks and conventions used across the StopWaste website. Whether you're creating a new page or updating an existing one, these patterns will help you build consistent, well-structured content.

• Page Structure by Level
• Wayfinding Cards
• Numbers Cards
• Accordion Blocks
• Images — Float vs. Image+Text
• Resource Lists
• Call to Action
• Heading Hierarchy & Jump Lists
• Separators
• Buttons & Links
• Other Blocks
• General Tips

---

Page Structure by Level

Every page on the site has a level (L1 through L4) that determines its role in the navigation hierarchy and what blocks it should use.

L1 — Hub Pages

These are the top-level entry points (Schools, Food, Compost & Gardening, etc.). They typically lead with a brief intro paragraph, followed by Wayfinding Cards pointing to the main L2 sections. Numbers Cards and a Call to Action are optional.

L2 — Section Pages

Section landing pages that sit below a Hub. Similar pattern to L1: brief intro, then Wayfinding Cards guiding users to L3 content pages. May include additional body content, resource lists, or a CTA.

L3 — Content Pages

The workhorse pages. Body content comes first (paragraphs, lists, headings), with optional Wayfinding Cards only if the page has L4 children below it. Use Accordion for FAQ-style content, Resource Lists for downloadables, and Buttons or a CTA for key actions.

L4 — Detail Pages

The most content-focused level. No wayfinding needed. Use Resource Lists for specific downloads and contact info at the bottom. Keep it straightforward.

---

Wayfinding Cards

Wayfinding Cards are the primary navigation block on landing pages. They guide users from an L1 or L2 page down to its child pages, displaying a card with an image, title, description, and link for each destination.

How They Work

Each card references a page by its node ID using the node field in the JSON settings. Drupal automatically pulls the image, heading, and description text from the referenced page — you do not need to set these manually. This keeps cards in sync when titles or descriptions change.

A typical card entry in the JSON looks like this:

{"remove_card":"Remove card","node":"4553","image":null,"heading":"","text":"","link":{"url":""}}

Notice that image, heading, text, and link are left empty — Drupal fills these in from the referenced node.

When to Override

You can manually set the heading, text, image, or link fields to override what Drupal pulls from the node. This is useful when you want a card's display text to differ from the page's actual title, or when pointing to an anchor or external URL. But in most cases, leave them empty and let the auto-pull do its job.

Layout and Limits

• Use 2-col layout for 2 cards, 3-col for 3 cards, 4-col for 4 cards.
• Never use more than 4 cards — if a section has more than 4 children, choose the top 3–4 most important.
• Default colorway: colorway-white.

Here's what Wayfinding Cards look like in practice — these cards point to pages about food recovery programs using only node IDs:

---

Numbers Cards

Numbers Cards highlight key statistics or quantified program impacts. They work best for drawing attention to measurable outcomes — tons diverted, schools served, dollars invested, etc.

Section Titles Go Inside the Block

An important convention: put the section title and any intro text inside the block's JSON settings using the heading and text fields. Do not add a separate H2 heading above the block. This keeps the heading visually connected to the statistics.

Card Structure

Each card needs three fields: icon (from the available icon set), heading (the stat number like "50 Years" or "$40 Million+"), and text (a brief description of what the number represents).

Default colorway is colorway-white. Do not place a separator before Numbers Cards blocks.

---

Accordion Blocks

Accordion blocks are ideal for FAQ sections, step-by-step instructions, or any content that benefits from progressive disclosure. Each item has a question (the clickable heading) and an answer (the expandable content).

Answer Formatting

The answer field uses plain HTML — not Gutenberg blocks. You can include paragraphs, bulleted lists, links, and bold text using standard HTML tags (<p>, <ul>, <li>, <a href>, <strong>). Keep answers concise and scannable.

Default colorway: colorway-white. You can also use colorway-neutral-100 for a light gray background.

---

Images — Float vs. Image+Text

There are two ways to include images in content, and they serve very different purposes.

Float Images (Most Common)

Use a standard wp:image block with "align":"right" to float an image alongside body content. This is the most common approach for adding visual interest to a content page. Always float images to the right. Place the image block after the section heading and before the following paragraph — the text will wrap around it naturally.

You can control the width using the "width" attribute (e.g., "width":"400px"). Include descriptive alt text for accessibility, and add a figcaption when useful context would help the reader.

<!-- wp:image {"align":"right","id":1234,"width":"400px","sizeSlug":"full",...} -->
<figure class="wp-block-image alignright size-full is-resized">
  <img src="/sites/default/files/..." alt="Description" style="width:400px" .../>
  <figcaption>Optional caption</figcaption>
</figure>
<!-- /wp:image -->

Image+Text Block (CTA Callouts Only)

The Image+Text block is a structured component with an image, heading, plain text, and one or two buttons. Use it only for special callouts with a distinct CTA — the block always has a button linking to another page. Do not use it just for visual interest alongside content.

Image+Text blocks have a presentation setting ("presentation":"align-right" or "align-left") that controls which side the image appears on. The text area is plain text only — no links or formatting.

---

Resource Lists

Resource Lists display downloadable documents, guides, and other attachments. Each card references a Resource node by its node ID — Drupal pulls the title, file type, and download link automatically.

Structure

The block JSON includes a heading field (like "Top Resources" or "Guides & Downloads"), optional text for an intro line, and a cards array where each card has a node field with the Resource node ID.

"cards":[
  {"remove_card":"Remove card","node":"4943"},
  {"remove_card":"Remove card","node":"4945"}
]

Look up node IDs from RESOURCES/all-resources.yaml when building these blocks. Default colorway: colorway-white.

---

Call to Action

The Call to Action (CTA) block is a full-width banner with an icon, heading, text, and one or two buttons. Use it as the primary action on a page — signing up for a program, contacting a team, submitting a request, etc.

Placement and Limits

• One CTA per page maximum. If a page needs multiple actions, use buttons in the body content and save the CTA for the most important one.
• Place the CTA at the end of the page, after all body content.
• Place the standard spacer block above the CTA, not below it.
• Do not place a separator before the CTA block.
• Default colorway: colorway-green-700.

Available icons include: lightbulb, compost, food-box, calendar, mail, and others. Choose one that relates to the action.

---

Heading Hierarchy & Jump Lists

Heading Levels

Use headings consistently to structure content:

• H2 (wp:heading) — Major sections. This is the default heading block.
• H3 (wp:heading {"level":3}) — Subsections within an H2.
• H4 (wp:heading {"level":4}) — Rarely used. Only within an H3 when truly needed.
• Don't skip levels (e.g., jumping from H2 directly to H4).

Jump Lists

For long pages with multiple H2 sections, add a jump list near the top of the page (after the intro paragraph) so users can navigate directly to each section. This page itself uses a jump list at the top.

To create a jump list:

1. Add an id attribute to each target H2 — use lowercase, hyphenated text (e.g., id="resource-lists").
2. Create a wp:list block near the top with anchor links matching each ID (e.g., <a href="#resource-lists">Resource Lists</a>).
3. Place the jump list after the intro paragraph and before the first separator or heading.

---

Separators

Separators create visual breaks between content sections. There are two styles, and they serve different purposes.

Normal Separator

A solid horizontal line. Use for major section breaks — typically after the intro paragraph on L1/L2 landing pages, or between genuinely distinct topics (e.g., separating program content from a wayfinding card group).

<!-- wp:separator -->
<hr class="wp-block-separator has-alpha-channel-opacity"/>
<!-- /wp:separator -->

Dots Separator

A dotted line. Use for minor divisions between related content sections — the most common style throughout the site.

<!-- wp:separator {"className":"is-style-dots"} -->
<hr class="wp-block-separator has-alpha-channel-opacity is-style-dots"/>
<!-- /wp:separator -->

When NOT to Use Separators

• Do not place separators before Numbers Cards, Icon Cards, or Call to Action blocks.
• Do not add separators between every H2 heading — consecutive content sections flow naturally.
• Do not place separators between H3 subsections.
• Rule of thumb: if removing the separator doesn't confuse the reader about where one topic ends and another begins, leave it out.

---

Buttons & Links

Button Blocks

Use button blocks for primary actions within the content flow — signing up, enrolling, downloading a key resource. Buttons are styled prominently and should be used sparingly. If there's a single most important action on the page, the CTA block is usually a better choice.

<!-- wp:buttons -->
<div class="wp-block-buttons"><!-- wp:button -->
<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="/path">Button Text</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons -->

Inline Links

For secondary references and cross-links, use standard inline links within paragraphs. Keep it natural — 1–2 related links per section is plenty. Use clean internal URLs (e.g., /schools/curriculum) for site pages and mailto: links for email contacts.

What to Avoid

• Do not prefix links with arrow characters (→). If a link deserves emphasis, make it a button.
• Do not use "click here" as link text. Use descriptive text that tells the reader what they'll find.

---

Other Blocks

Icon Cards

Icon Cards categorize content using icons — useful for grouping items by type (grade levels, waste categories, character types). Each card has an icon, heading, text, and optional link. Available icons include: oil, food-box, pest, juice-box, avocado, compost, and others. Layout options mirror Wayfinding Cards (2-col, 3-col, 4-col). Do not place a separator before Icon Cards.

Content Cards

Content Cards link to related pages or top resources. Like Wayfinding Cards, each card references a node ID and Drupal pulls the content automatically. They include an optional heading, intro text, and a button. Use them sparingly — they're best for cross-referencing content from other sections of the site.

Quote Blocks

The wp:quote / blockquote element should only be used for actual quotes from a person. Do not use it for callouts, "did you know" facts, or highlighted content — use a bold paragraph or Numbers Card for those instead.

Embedded Video

YouTube videos can be embedded using the wp:embed block. Just provide the video URL and Drupal handles the rest.

Tables

Standard HTML tables wrapped in a wp:table block. Include a thead for headers. Use tables for structured data — schedules, comparison charts, program details. Keep them simple; if a table gets too complex, consider an accordion or list instead.

---

General Tips

Spacer Blocks

Every page should end with a spacer block to create breathing room at the bottom. If the page ends with a CTA, place the spacer above the CTA. The standard spacer is 100px:

<!-- wp:spacer -->
<div style="height:100px" aria-hidden="true" class="wp-block-spacer"></div>
<!-- /wp:spacer -->

Voice and Tone

• Write in a clear, direct, action-oriented voice.
• Focus on what users can do — sign up, learn more, find resources.
• Avoid jargon. If a technical term is necessary, explain it briefly.
• Use active voice over passive ("We provide grants" not "Grants are provided").

Cross-Linking

Link related content across sections to help users discover relevant programs. Use contextual links within body text — for example, a food waste page might link to the composting section, or a school program page might reference available grants. Keep it to 1–2 related links per section to avoid clutter.

Page Metadata

Every page has three metadata fields that appear outside the body content:

• Hero Title — the longer title displayed at the top of the page.
• Title — shorter title used in breadcrumbs and navigation.
• Description — 1–2 sentence summary shown in Wayfinding Cards and search results. Keep it concise and informative.