Statewatch Editor & Administrator Guide

Site: statewatch.org Theme: state-main Companion plugin: statewatch-xml-importer Audience: Editors, content managers, site administrators Version: 0.1 (draft skeleton — 2026-04-25)

Document status

This is the skeleton of the full editorial guide. Each section currently contains:

• A short description of what the section will cover

Filled-in sections will replace this skeleton incrementally. See Section 0 below for the production plan and current progress.

Table of contents

• 0. Production plan
• 1. Introduction
  • 1.1 Purpose of this guide
  • 1.2 Who should read it
  • 1.3 How the site is built (high level)
  • 1.4 Key terminology
• 2. Getting started
  • 2.1 Logging in
  • 2.2 The WordPress dashboard
  • 2.3 User roles and permissions
  • 2.4 Editorial conventions at Statewatch
• 3. Content model overview
  • 3.1 Map: post types ↔ taxonomies ↔ blocks
  • 3.2 Why one CPT for many "types"
  • 3.3 How a piece of content reaches the front page
• 4. Custom Post Types (CPTs)
  • 4.1 statewatch_article — Articles, Documents, Events, Research, Annual Reports
  • 4.2 sw_focus_area — Focus Areas
  • 4.3 person — Team profiles
  • 4.4 job — Job openings
  • 4.5 page — Standard WordPress Pages
• 5. Taxonomies
  • 5.1 sw_content_type — hierarchical content classifier
  • 5.2 sw_status — Active / Archived
  • 5.3 sw_section — folder hierarchy mirror
  • 5.4 sw_article_source — Umbraco legacy source
  • 5.5 sw_keyword
  • 5.6 sw_topic
  • 5.7 sw_org — organisations
  • 5.8 sw_institution
  • 5.9 sw_legislation
  • 5.10 person-category
• 6. ACF Blocks — editor reference (28 blocks)
  • 6.1 How ACF blocks work in this site
  • 6.2 Hero & headers
    • hero
    • hero-title-text
    • hero-title-image
  • 6.3 Body & layout
    • title-text
    • title-text-image
    • article-body
    • pull-quote
    • what-we-do
    • embed-iframe
  • 6.4 Calls to action & forms
    • accordions
    • accordions-wide
    • cta-banner
    • support-cta
    • contact-form
    • contact-columns
  • 6.5 Topical navigation
    • focus-areas
    • focus-areas-tiles
  • 6.6 Search & curated lists
    • search
    • related-documentation
  • 6.7 Listings (auto-queried)
    • latest-articles
    • all-articles
    • latest-resarch
    • all-research
    • all-documents
    • all-events
    • upcoming-events
    • annual-reports
    • jobs
    • people
• 7. Single post layouts
  • 7.1 Article single (single-article.twig)
  • 7.2 Document single (single-document.twig) — sidebar + PDF viewer
  • 7.3 Event single (single-event.twig)
  • 7.4 Research single (single-research.twig)
  • 7.5 Focus Area single (single-focus-area.twig)
  • 7.6 Person single (single-person.twig)
  • 7.7 Job single (single-job.twig)
• 8. Documents — special editing rules
  • 8.1 Why documents differ from articles
  • 8.2 The _swxi_sdp_* ACF fields explained
  • 8.3 Editing a document step by step
  • 8.4 Where each field appears on the front-end
• 9. Authors — assigning posts and where they appear
  • 9.1 Setting the post author
  • 9.2 Multiple / co-authors
  • 9.3 Where the author is displayed on the front-end
  • 9.4 Author profile pages
• 10. Media library
  • 10.1 Image requirements
  • 10.2 Automatic AVIF / WebP generation
  • 10.3 Alt text and accessibility
  • 10.4 PDF uploads (for documents)
• 11. Forms & newsletter
  • 11.1 Contact form
  • 11.2 Newsletter (Brevo)
• 12. Statewatch XML Importer — for administrators
  • 12.1 What it is and what it does
  • 12.2 Umbraco → WordPress mapping (cheat sheet)
  • 12.3 Editing imported content
  • 12.4 Re-running an import
  • 12.5 The two commands: import-structure then import
  • 12.6 Where to access the importer
  • 12.7 Excluded content (/statewatch-database/)
• 13. Common editorial workflows (recipes)
  • 13.1 Publish a News article
  • 13.2 Add a Document with PDF
  • 13.3 Add an upcoming Event
  • 13.4 Move an article to Archived
  • 13.5 Add a person to the team page
  • 13.6 Post a job opening
  • 13.7 Create a Focus Area landing page
  • 13.8 Update the homepage hero
• 14. Card components — taxonomy & field mapping
  • 14.1 Article card — large variant
  • 14.2 Article card — small variant
  • 14.3 Document card
  • 14.4 Research card
  • 14.5 Annual report card
  • 14.6 Event card
  • 14.7 Person tile
  • 14.8 Job row
  • 14.9 Focus area tile
  • 14.10 At-a-glance: which taxonomy lands where
• 15. Glossary
• Appendix A — Field reference (meta keys)
• Appendix B — Troubleshooting

0. Production plan

The guide will be filled in sections, in this order. Each milestone is reviewable on its own.

After all milestones: final consistency pass, then convert to .docx via Pandoc.

1. Introduction

1.1 Purpose of this guide

This guide is the single reference for everyone who edits, publishes, or administers content on statewatch.org. It documents the entire content surface — the post types you can create, the taxonomies you fill in, the blocks you place on a page, and the rules that govern how each piece of content is rendered on the front-end.

It covers, in order:

1. What things are — the content model: post types, taxonomies, single page layouts.
2. What you put in them — every ACF block you can add to a page, with field-by-field documentation.
3. How to do common jobs — recipe-style walkthroughs (publish a news article, add a document with a PDF, archive an article, post a job, etc.).
4. Administrator topics — author management, media, forms, the Statewatch XML Importer (Umbraco → WordPress).

If you find something in the guide that is wrong, outdated, or unclear, ping the technical lead — every section ends with the source-of-truth file path so you can verify yourself before reporting.

1.2 Who should read it

1.3 How the site is built (high level)

You only need this background to make sense of the rest of the document. No coding required to use it.

• WordPress is the underlying CMS. Everything you do happens in wp-admin. All the standard WordPress concepts apply: posts, pages, users, media library, taxonomies.
• Timber + Twig is the templating layer. Editors never see Twig — but if a developer says "the Twig template renders X", that just means: the visual layout of the front-end is generated by template files, separate from the editor.
• ACF (Advanced Custom Fields) Blocks are the building blocks of every page. There are 28 of them. Each one has a defined set of fields (title, image, list of items, etc.) and produces one rendered section on the front-end. You compose pages by stacking blocks. See Section 6 for the full reference.
• Statewatch XML Importer is a custom plugin that imported ~29,000 articles from the previous Umbraco CMS into WordPress. It still ships with the site and can re-import or update content. Editors normally do not run it — see Section 12 for the admin guide.
• Bootstrap 5 powers the design system: spacing, breakpoints, typography classes. You generally do not edit Bootstrap directly; the styles you write inside ACF blocks already inherit the design system.

1.4 Key terminology

2. Getting started

2.1 Logging in

• Production: https://statewatch.org/wp-admin/
• Staging: https://philosophical-teal-bobcat.b0c6b556d4a9fbd633a2a4f7e1d3cc8f-14859.sites.k-hosting.co.uk/wp-admin/
• Local development: http://state-main.local/wp-admin/

The Staging environment is the safe place to preview editorial and structural changes before they go live on production. Editors should test new posts, importer runs, plugin updates, and any cross-cutting visual changes there first; once the result looks right, replicate the change on production (or ask an administrator to promote the staging build, if that workflow has been set up).

Use the credentials you were given separately. If you forget your password, click "Lost your password?" on the login screen — a reset link will be emailed to the address on your user profile.

Security – Do not share credentials over chat or email. – Staging may contain real (copied) editorial content. Treat it with the same care as production.

2.2 The WordPress dashboard

After login you land on the WordPress dashboard. The left-hand sidebar is your map of the entire site. The order of items has been customised to mirror the website's information architecture — content menus appear at the top in roughly the same order as the public navigation, with administrative items (Appearance, Users, Tools, Settings, ACF) below.

Hidden by default: Posts and Comments. Statewatch does not use the standard WordPress post type or comments — all editorial content lives in the custom post types listed below. Both menus remain reachable by direct URL (/wp-admin/edit.php, /wp-admin/edit-comments.php) for the rare case an administrator needs them, but they are removed from the sidebar to keep it focused.

How the content menus work. Most editorial menus you see (Articles, Research, Events, Annual Reports, Documents) are virtual menus added by the Statewatch XML Importer plugin. Each one opens the same statewatch_article post-list filtered by a sw_content_type term — so they are different windows onto one underlying post type. All Posts directly under them (formerly labelled Statewatch) is the unfiltered post-list of that same CPT (every article regardless of content type). Source: wp-content/plugins/statewatch-xml-importer/src/Admin/ContentTypeMenu.php + Admin/EditorUX.php (reorder + hide).

The number badge next to each label is the live count of posts whose sw_content_type matches that term.

The sidebar order, top to bottom (Statewatch-specific items only — default Dashboard, Appearance, Users, Tools, Settings behave as in any WordPress install):

2.3 User roles and permissions

Statewatch uses the standard WordPress role set:

2.4 Editorial conventions at Statewatch

[TO BE WRITTEN WITH EDITORIAL TEAM INPUT] — placeholder for: voice and tone, capitalisation of headlines, when to publish as Article vs. Document, image-rights checklist, archive policy (when to flip sw_status to Archived), translation handling.

3. Content model overview

3.1 Map: post types ↔ taxonomies ↔ blocks

This is the single most important diagram in the guide. Spend a minute on it before reading the rest.

                                    ┌─────────────────────────────────┐
                                    │       statewatch_article        │
                                    │   (one CPT, many "kinds")        │
                                    └─────────────────────────────────┘
                                                 │
        ┌────────────────────────────────────────┼────────────────────────────────────────┐
        │                                        │                                        │
        ▼                                        ▼                                        ▼
   sw_content_type                          sw_status                             sw_section / sw_keyword
   (hierarchical — what KIND of post)       (Active / Archived)                   sw_topic / sw_org
                                                                                  sw_article_source
   ├── Articles                                                                   sw_institution
   │   ├── News                                                                   sw_legislation
   │   └── Analyses                                                               (multi-tag classification)
   ├── Research
   │   ├── Bulletins
   │   ├── Reports
   │   ├── Journal
   │   ├── Observatories
   │   ├── Projects
   │   └── Semdoc
   ├── Events
   ├── Documents
   └── Annual Reports

      ↓                                       ↓                                          ↓
  decides which                         filters out of                           feeds the dropdown
  single-*.twig                         "latest" listings                          filters in listing
  template renders                                                                blocks (all-articles,
                                                                                  all-documents, etc.)

Other CPTs (independent of statewatch_article):

sw_focus_area  ──→  rendered by single-focus-area.twig  ──→  linked to from focus-areas / focus-areas-tiles blocks
person         ──→  rendered by single-person.twig      ──→  listed by the `people` block
job            ──→  rendered by single-job.twig         ──→  listed by the `jobs` block

3.2 Why one CPT for many "types"

statewatch_article covers Articles, Documents, Events, Research, and Annual Reports as a single WordPress post type. The differentiation is done via the sw_content_type taxonomy.

This is a deliberate architectural choice carried over from the migration:

• All five "kinds" share the same underlying structure (title, body, dates, author, taxonomies, meta fields).
• The XML importer already normalised the three Umbraco document types (JhaArticle, CmsArticle, DBArticle) into one shape — splitting them on the WordPress side would have been busywork.
• Cross-type queries become trivial. A "latest content of any kind" feed is one WP_Query. The same admin search box finds anything.
• Caching and indexing benefit from a single wp_posts row layout.

The trade-off is that the kind of an article is not visible in the URL by default — you have to look at the sw_content_type term. The single template (single-statewatch_article.php) handles this automatically: it inspects the taxonomy and routes to the right Twig file (single-article.twig, single-document.twig, single-event.twig, single-research.twig).

Practical consequence for editors: Always set Content type correctly when creating an article. If you forget to set it, the post will fall back to the generic single-article layout and may not appear in the listing block you expect.

3.3 How a piece of content reaches the front page

Worked example: publishing a news article about EU border policy.

1. Create the post. Articles → Add New. Title and body content go in like a regular WordPress post.
2. Assign Content type. Open the Content type taxonomy box → expand Articles → tick News. (Hierarchical — you can pick the parent or a child.)
3. Assign tags. Add sw_keyword, sw_topic, sw_org terms as appropriate. These drive filter dropdowns in listings.
4. Set Status. Default is Active. Archived items are hidden from "latest" feeds but remain searchable.
5. Set the Author. Sidebar → Document → Author dropdown (see Section 9.1).
6. Set the Featured Image. Used as the card thumbnail in listing blocks.
7. Publish.
8. Verify front-end: open https://statewatch.org/articles/ — your post should appear at the top, filtered by the News dropdown. The same post will also surface in:
9. The latest-articles block on the homepage.
10. The all-articles block on the Articles archive page.
11. The taxonomy archive of any sw_keyword term you tagged it with.

If the article does not show up where you expected, the cause is almost always one of:

• Content type is missing or wrong.
• Status is Archived.

4. Custom Post Types (CPTs)

There are five post types you will work with on Statewatch. Four are custom; one is the standard WordPress page. Below is a quick reference, then a detailed section for each.

Why are People and Jobs registered via ACF UI? ACF PRO 6.1+ ships a UI for registering post types and taxonomies directly from wp-admin → ACF → Post Types. They are stored in the database, not in code. To export them or move between environments, use ACF → Tools → Export. They are not in acf-json/ because Local JSON sync is not configured in this theme.

4.1 statewatch_article — Articles, Documents, Events, Research, Annual Reports

Admin label in sidebar: All Posts (icon: document) Slug: statewatch_article URL pattern: dynamic — built from the sw_section term hierarchy. Examples: - News article → /news/2025/december/{slug}/ - Document (JHA archive) → /jha-archive/{slug}/ - Document (publications) → /publications/{slug}/ - Research report → /publications/reports-and-books/{slug}/ - Event → /publications/events/{slug}/

Registration: wp-content/plugins/statewatch-xml-importer/src/PostTypes/ArticlePostType.php

Supports: title, editor (Gutenberg), excerpt, custom fields, thumbnail (featured image)

Taxonomies: sw_content_type (decides the layout), sw_status, sw_section, sw_article_source, sw_keyword, sw_topic, sw_org, sw_institution, sw_legislation — see Section 5 for each.

ACF fields specific to articles:

Full meta-key reference is in Appendix A. Front-end placement of each meta key is documented in Section 8.4.

Editor sidebar — what is hidden by design The Sources (sw_article_source) and Sections (sw_section) taxonomy panels are intentionally hidden from the post-edit screen for statewatch_article. Both are managed by the importer and the auto-section assignment routine; editing them by hand causes broken hierarchical permalinks and mis-classified content. They remain editable from the taxonomy admin pages (/wp-admin/edit-tags.php?taxonomy=sw_section etc.) for the rare cases where a real change is needed. Source: Admin/EditorUX.php (hideTaxonomyMetaBoxes + Gutenberg removeEditorPanel script).

The Yoast SEO meta box has also been moved to the bottom of the sidebar (priority low) so editors fill in editorial fields — taxonomies, author, ACF — before SEO.

Where it appears on the front-end:

• Listed by the latest-articles block (homepage) — Articles content type, latest 10
• Listed by all-articles block — Articles archive page
• Listed by all-documents block — Documents archive
• Listed by all-research / latest-resarch blocks — Research pages
• Listed by all-events / upcoming-events blocks — Events page
• Listed by annual-reports block — annual reports landing
• Cross-referenced from single-person.twig (related articles by author)
• Cross-referenced from single-focus-area.twig (articles whose sw_keyword or sw_topic terms intersect with the focus area's Keywords / Topics ACF fields)

Admin list view:

Edit view:

Front-end (Article single):

Front-end (Document single):

4.2 sw_focus_area — Focus Areas

Admin label: Focus Areas (icon: flag) Slug: sw_focus_area URL pattern: /focus-area/{slug}/ (singular — the slug really is focus-area, not focus-areas) Registration: wp-content/plugins/statewatch-xml-importer/src/PostTypes/FocusAreaPostType.php Supports: title, editor, excerpt, thumbnail

Existing focus areas on the site (from the homepage at the time of writing):

• Borders and frontiers
• Coercion and control
• Collusion and crime
• Discrimination and racism
• Peace and war
• Secrecy and transparency
• Resistance and solidarity
• Snooping and surveillance

Where it appears on the front-end:

• Listed by the focus-areas block (long list, e.g. on the homepage)
• Listed by the focus-areas-tiles block (tiled grid, e.g. on the Our work page)
• Has its own single page (single-focus-area.twig) which shows the focus area description plus related articles and research

⚠ Known issue: the taxonomy archive at http://state-main.local/focus-area/ (without a slug) currently returns a 500. The individual focus-area pages work fine. This is a developer todo, not an editor issue.

Custom fields (verified in single-sw_focus_area.php):

Admin edit view:

Front-end:

4.3 person — Team profiles

Admin label: People Slug: person URL pattern: /person/{slug}/ Registration: ACF UI Post Types (DB-level, not in code) Single template: single-person.php → views/single-person.twig

ACF fields (confirmed by reading single-person.php):

Taxonomy: person-category (attached to person CPT). Known terms include staff. Other terms drive the filter on the people block.

Where it appears on the front-end:

• Listed by the people block (with category filtering — Staff shown by default, other categories selectable)
• Has its own single page (single-person.twig) showing pronouns, position, contact links, and all articles + research where this person is set as Author (sw_author).

Admin edit view:

Front-end:

4.4 job — Job openings

Admin label: Jobs Slug: job URL pattern: /job/{slug}/ Registration: ACF UI Post Types (DB-level, not in code) Single template: single-job.php → views/single-job.twig

ACF fields (confirmed by reading single-job.php):

Date format trap: Closing date (closed_date) is stored as a string in d/m/Y. The single template parses it with DateTime::createFromFormat('d/m/Y', …). Any other format (e.g. ISO 2026-06-30) will silently fail and the job will appear forever as open. The ACF Date Picker for this field is configured to output d/m/Y.

Sidebar option used by single-job.twig: ACF Link field All jobs page (our_jobs) on the theme options page — sets the "Back to all jobs" URL.

Where it appears on the front-end:

• Listed by the jobs block on the Work with us page
• Has its own single page (single-job.twig) with the apply button + "Other open jobs" sidebar

Admin edit view:

Front-end:

4.5 page — Standard WordPress Pages

Admin label: Pages (built-in) Slug: page Single template: page.php (Timber) — composes whatever ACF blocks the editor placed inside Gutenberg.

Pages on the live site (confirmed by crawling the menu):

Editor tip: when in doubt, the front-end View Page Source will tell you which ACF blocks are on a page (they render as <section class="blk-{name}">).

Front-end (Home):

5. Taxonomies

There are ten taxonomies in the system. Nine are attached to statewatch_article. One (person-category) is attached to person. Focus areas (sw_focus_area) are a CPT, not a taxonomy.

All sw_* taxonomies are registered by the Statewatch XML Importer plugin in wp-content/plugins/statewatch-xml-importer/src/Taxonomies/*.php. Reactivating the plugin re-runs registration.

5.1 sw_content_type

Hierarchical · attached to statewatch_article · admin column visible

The single most important taxonomy. It decides:

1. Which front-end single template renders the post (single-article.twig / single-document.twig / single-event.twig / single-research.twig).
2. Which listing block picks the post up (all-articles queries News + Analyses; all-documents queries Documents; all-events queries Events; etc.).
3. The breadcrumb on archive listings.

Term tree (verified against ContentTypeTaxonomy.php):

Articles
├── News
└── Analyses
Research
├── Bulletins
├── Reports
├── Journal
├── Observatories
├── Projects
└── Semdoc
Events
Documents
Annual Reports

Editorial guidance

• Always pick a leaf term, not a parent, when one exists. Use News (not Articles) for a news article. Parents are containers, not labels.
• A post can have multiple terms (e.g. a Reports + Journal cross-publication), but in practice almost every post has exactly one. Assign multiple only when there is a real reason.
• Renaming a term changes its slug if you also tick "edit slug" — this breaks any URL that was relying on /sw_content_type/{slug}/. Do not rename slugs once they are live.

5.2 sw_status — Active / Archived

Flat · attached to statewatch_article · two fixed terms

Source: StatusTaxonomy.php. The two terms are constants:

Auto-assignment on import: the XML Importer sets archived automatically when the source URL contains /archive/, -archive/, or /archived/. Everything else is active.

Editorial guidance

• Move articles to Archived when they become outdated but still have historical value.
• Do not invent new terms — the codebase only handles these two.
• Flipping to Archived is reversible without side effects.

5.3 sw_section

Hierarchical · attached to statewatch_article · drives the URL of every article

Source: SectionTaxonomy.php. Mirrors the original Umbraco folder structure — about 527 terms for CmsArticles plus parents.

Critical role: the article URL is built from the section path. The CPT registers its rewrite slug as '%sw_section%', which means the section term hierarchy literally becomes the URL. For example:

• An article assigned to section news → year 2025 → month december produces a URL like /news/2025/december/{post-slug}/.

Slug convention: terms use the last path segment only. So the term for news-2025-january is just january — its parent is 2025, whose parent is news. This avoids "news-2025-january" appearing twice in URLs.

Auto-population: - Run by wp swxi import-structure (Section 12.5) once, before the first article import. - New articles published manually after the import are auto-assigned to News → {Year} → {Month} by the plugin (filterable via swxi_auto_section_parent — developer-only).

Editorial guidance

• For new articles, you usually do not need to set this manually — the plugin auto-assigns based on publish date.
• If you create a fundamentally new section (e.g. a new annual focus), coordinate with the dev team — adding a top-level section needs a code change in ContentTypeMapper.php (PATH_MAPPINGS) to keep importer URL→type mapping consistent.

Hidden from the post-edit screen. The Sections meta box / Gutenberg panel is hidden on statewatch_article edits to prevent accidental URL breakage. Manage terms via All Posts → Sections in the admin (/wp-admin/edit-tags.php?taxonomy=sw_section&post_type=statewatch_article). Source: Admin/EditorUX.php.

5.4 sw_article_source — legacy Umbraco source

Flat · attached to statewatch_article · admin column visible · rewrite slug /source/

Source: ArticleSourceTaxonomy.php. Records which legacy Umbraco document type produced the article:

Editorial guidance

• Do not change this for imported posts unless you understand it changes the rendered layout.
• For brand-new posts written natively in WordPress, you can leave this blank — the layout is then driven solely by sw_content_type.

Hidden from the post-edit screen. The Sources meta box / Gutenberg panel is hidden on statewatch_article edits — the value is set by the importer and editing it by hand changes which single template is rendered. Manage terms via the taxonomy admin page if a real change is ever needed. Source: Admin/EditorUX.php.

5.5 sw_keyword — Statewatch Keywords

Flat · attached to statewatch_article · admin column visible · rewrite slug /statewatch-keyword/

Source: KeywordsTaxonomy.php. The most-used "tag" taxonomy.

Originally populated from Umbraco fields Sdp_keywords, Sdp_statewatchkeywords, and Keywords (merged). Editors add new keywords as needed.

Where it surfaces on the front-end

• Listed at the bottom of every article single page as clickable tags.
• Drives the Keyword filter dropdown on all-articles, all-documents, etc.
• Each keyword has its own taxonomy archive: /statewatch-keyword/{slug}/.

Editorial guidance

• Reuse existing keywords whenever possible. Use the term selector's autocomplete.
• Use lowercase, hyphen-separated, plural where natural (e.g. border-controls, not Border Control).
• A starter list of ~hundreds of keywords ships with the imported content (see statewatch-keywords.xlsx in the importer plugin).

5.6 sw_topic — Statewatch Topics

Flat · attached to statewatch_article · admin column visible · rewrite slug /statewatch-topic/

Source: TopicTagsTaxonomy.php. Populated from Umbraco TopicTags (DBArticle-only).

Editorial use: complementary to sw_keyword. Topics are broader thematic groupings (e.g. Migration, Counter-terrorism) while keywords are granular (e.g. Schengen-information-system, border-externalisation). Reuse existing terms — see statewatch-topics.xlsx in the importer plugin for the imported set.

5.7 sw_org — Statewatch Organisations

Flat · attached to statewatch_article · admin column visible · rewrite slug /statewatch-org/

Source: OrganisationalTagsTaxonomy.php. Populated from Umbraco OrganisationalTags (DBArticle-only).

Editorial use: the organisation(s) the article is about (e.g. Frontex, Europol, European Commission), not the publisher. For document publishers, use the Publisher (_swxi_sdp_publisher) meta field (see Section 8.2). Reference list: statewatch-organisations.xlsx in the importer plugin.

5.8 sw_institution

Flat · attached to statewatch_article · no admin column · rewrite slug /institution/

Source: InstitutionTaxonomy.php. Less commonly used — typically reserved for Documents that originate from a specific EU institution (Council of the EU, European Parliament, Commission DGs).

Editorial guidance

• Mostly relevant on Documents (especially JHA archive).
• Use only when the institution distinction matters for filtering. If the article is just about an institution, sw_org is usually the right choice.

5.9 sw_legislation

Flat · attached to statewatch_article · no admin column · rewrite slug /legislation/

Source: LegislationTaxonomy.php. Tags articles that reference specific pieces of EU legislation (regulations, directives, framework decisions).

Editorial guidance

• Use formal legislation IDs as terms (e.g. Regulation (EU) 2024/1234, Directive 2008/115/EC).
• Mostly relevant for Documents and analyses. News articles rarely need this.

5.10 person-category

Hierarchical · attached to person CPT · registered via ACF UI (DB-level)

Drives the category filter on the people block. The staff term is treated specially in the block's render.php — it appears first in the tab list, and is the default selected category on page load.

Known terms: staff (treated specially — pinned first in the people block tab list). Additional categories can be added in the admin and are surfaced as additional tabs alphabetically.

Editorial guidance

• New categories appear as new filter tabs on the About us / Team page automatically.
• Order on the front-end: Staff first, then alphabetical.

6. ACF Blocks

6.1 How ACF blocks work

Every visual section on Statewatch is built from an ACF block. A page is just a vertical stack of blocks, each filled with structured fields by an editor. There are 28 blocks — they are documented in §6.2 (hero & headers), §6.3 (content), and §6.4 (listings).

Adding a block

1. Open a page or post in Pages → Edit / Articles → Edit.
2. Click the + (Block Inserter) in the top-left of the Gutenberg toolbar.
3. Find the Theme category (or search by name, e.g. "Hero") — every Statewatch block lives there.
4. Click the block. It is inserted at the cursor position.
5. Fill the fields in the block's settings panel (right sidebar).

Moving / duplicating / removing

Use the floating block toolbar that appears when a block is selected:

• ⋮⋮ (drag handle) — drag to reorder.
• ↑ / ↓ — move one position up/down.
• ⋯ (kebab menu) → Duplicate, Remove, Copy block.

Alignment

Most blocks support two alignments:

• Wide width — slightly wider than the content column. Good for image-heavy blocks.
• Full width — edge-to-edge of the viewport. Default for hero blocks.

The toolbar shows the alignment buttons; the active state is the only one rendered on the front-end.

Spacing (padding / margin)

Blocks that include 'spacing' => ['padding', 'margin'] in their config can be tuned per-instance from the Dimensions panel in the block sidebar. Use sparingly — most blocks already include sensible default spacing.

In-editor preview vs. front-end

Every Statewatch block uses ACF's mode: preview — the editor renders the actual front-end output. This means what you see in the editor is what gets shipped, with two caveats: - AJAX-driven listings (e.g. filter dropdowns in all-articles) show the static initial state in the editor. - Animations (e.g. fade-up on scroll) do not run in the editor.

Asset loading

Each block has its own SCSS and TypeScript bundle. The bundle is enqueued only on pages where the block actually appears (handled by Enqueue.php via the block's enqueue_assets callback). Adding a block to a page therefore has zero cost on pages that do not use it.

Reading this section

Each block below follows the same layout:

• Purpose — one sentence.
• Where it is used — typical pages on the live site.
• Fields — the editable inputs, with type and notes. Verified against views/blocks-acf/{block}/template.twig (the source of truth — every fields.* reference in the Twig is documented here).
• Editorial guidance — copy length, image dimensions, common pitfalls.
• Front-end — Figma reference + current site screenshot.
• Admin notes — technical caveats (AJAX filters, custom render.php, dependencies).

6.2 Hero & headers

hero

Purpose: Full-bleed homepage hero. Background image with a featured-post card overlaid bottom-right.

Where it is used: The Home page (/).

Fields (verified against views/blocks-acf/hero/template.twig):

Front-end (Figma — block view):

The featured-post card overlaid on the bottom-right of the hero:

Front-end (state-main.local):

Admin notes

• The post card is rendered by views/partials/post-card.twig. Card colours and tags are driven by the post's taxonomies, not by the hero block.
• This block has mode: preview, so the Gutenberg editor shows the actual hero with the chosen image and post.

hero-title-text

Purpose: Page-header band with a large title plus supporting text and an optional CTA button. No image.

Where it is used: Section/landing pages where the title carries the visual weight: /articles/, /research/, /documents/, /events/, /about-us/, /work-with-us/.

Fields (verified against template.twig):

Front-end (Figma — full row, title left + intro/button right):

Same component is used as page header on Articles, Research, Documents, Events, About, Work with us pages.

Front-end (state-main.local):

Admin notes

• Field group not in config.php — fields registered via ACF UI. Check Custom Fields → Field Groups → "Hero title text" to inspect or modify.

hero-title-image

Purpose: Two-column hero with a title + body text + button on the left, and a portrait/feature image on the right.

Where it is used: Story-led pages where the image carries meaning: /our-work/, /donate/, /work-with-us/, /about-us/ (top section).

Fields (verified against template.twig and the acf_add_local_field_group call in config.php):

Front-end (Figma — full row, text left + image right):

Used as the top section of the Our work / Donate / About us pages.

Front-end (state-main.local — Our work):

Admin notes

• This is the only hero block whose ACF fields are defined in code (acf_add_local_field_group in config.php). The other two are registered via the ACF UI. Practical consequence: changes to Hero title image fields require a code change; changes to the others are click-to-edit in wp-admin → Custom Fields.

6.3 Body & layout

title-text

Purpose: Two-column heading block — H2 on the left, supporting paragraph + optional CTA on the right. The most common "section header" on long pages.

Where it is used: As a section divider on landing pages (homepage between hero and listings, About page between sections).

Fields:

Front-end (Figma — full row, title left + body/button right):

title-text-image

Purpose: Same as title-text but with a feature image on the right column. Two-column layout that swaps to image-on-top on mobile.

Where it is used: Story-led sections on About / Donate / Our work pages.

Fields:

Front-end (Figma — full row, title/text left + image right):

article-body

Purpose: The rich-text body of an Article or Research single page, with an optional sticky table-of-contents side menu built automatically from H2 / H3 / H4 headings inside the WYSIWYG.

Where it is used: Inside individual articles and research posts.

Fields:

The body content itself is structured by headings, not by separate blocks. A single article-body block contains the entire article as one WYSIWYG field. To create the visible sub-sections you see on the live site (e.g. "The cost of Fortress Europe", "Reclaiming migration", etc.), insert H2 headings inside the WYSIWYG. The JavaScript on the article page reads every H2 / H3 / H4 from the body and:

1. Auto-assigns each heading an HTML id (slugified from the heading text).
2. Builds the left-column side menu (the dark/green list seen on long articles) listing each heading as a clickable link.
3. Adds scroll-spy: the link of the heading currently in view becomes "active" (highlighted with the green arrow).
4. Smooth-scrolls to the heading when its link is clicked.

Two TOC mechanisms exist on article pages — they are different:

• Page-level TOC (single-article__toc) — built by initArticleToc() from headings inside .single-article__content (the main post body). This is the side menu visible on every long article single.
• Block-level TOC (blk-article-body__toc) — built by the article-body block's own view.ts from headings inside its own .blk-article-body__wysiwyg element, only when Show sidebar is ON.

If both are present, the page-level one renders the master menu in the article single layout, and the block-level one is a redundant copy. In normal use you only need to leave Show sidebar OFF — the page-level TOC handles everything.

How to create body sub-sections (editorial steps):

1. In the Content WYSIWYG, place the cursor where the new section should start.
2. Use the format dropdown (or keyboard shortcut Cmd+Alt+2) to make the line a Heading 2.
3. Type the section title.
4. Continue with body paragraphs / images / quotes underneath.
5. Repeat for each section. Use Heading 3 for nested sub-sections; the side menu indents them automatically.
6. Save / Update — the side menu rebuilds on the next page load.

Footnotes / endnotes (how to write them):

The article body supports automatically wired footnotes for both Word-pasted content and manually authored notes. The mechanism lives in app.ts → initArticleFootnotes() and runs only on article single pages.

To use footnotes:

1. In the body, where you want the reference, insert a link with href="#fn-N" (where N is the note number) and the visible text being the number itself. Example: <a href="#fn-1">1</a> — pasted from Word, the link will look like <a href="#_bookmark1">…</a> and is also accepted.
2. At the very end of the article body, add a final ordered list (<ol>) where each <li> is a single footnote. Each footnote item should contain at least one external link (http…) — the script uses this to recognise the OL as the footnote list (separating it from any other ordered lists you may have used inside the article).
3. The script then auto-wires:
4. Wraps each inline reference in <sup> so it renders as superscript.
5. Assigns IDs fnref-N (inline) and fn-N (in the list).
6. Inserts an "Endnotes" heading above the list.
7. Appends a back-link ↩ at the end of each footnote item.
8. On desktop (≥992 px viewport), hovering an inline reference opens a small popover on the right side of the content column showing a preview of the footnote.

Editorial note: if the article has fewer footnote items in the OL than inline references in the body, the surplus inline references are still wired but their popover will be empty. Always keep the count matched.

Front-end (Figma — full section with side menu visible):

Front-end (Figma — content area only):

pull-quote

Purpose: A blockquote-style pull-quote with an optional author attribution. Used to break up long-form articles.

Where it is used: Inside long Articles / Research posts.

Fields:

Front-end (Figma — section view):

what-we-do

Purpose: Two-column "manifesto" section — title + body + CTA on the left, large image on the right. Larger and more visually heavy than title-text-image.

Where it is used: Homepage and About page top sections.

Fields:

Front-end (Figma — full row, text left + image right):

embed-iframe

Purpose: Drop in any external embed snippet — YouTube / Vimeo videos, datawrapper / Flourish charts, Google Maps, Airtable, Twitter/X posts, etc. Editor pastes the full <iframe> (or oEmbed-style) HTML and the block renders it inside a responsive ratio wrapper.

Where it is used: Long-form Research posts and Article bodies that need a visualisation, a video, or a third-party widget. Available in any place ACF blocks can be added.

Fields:

Editorial workflow: 1. On the source platform, click Share → Embed and copy the full snippet. 2. In Gutenberg, add a Embed (iframe) block. 3. Paste the snippet into Embed code. 4. Pick the aspect ratio that matches the source. Most YouTube/Vimeo videos are 16x9; most datawrapper / Flourish charts use auto. 5. Optional: add a caption. 6. Save and preview — the editor preview renders the actual embed, not just a placeholder.

Full-bleed in Research: when this block is placed inside a Research single post (i.e. sw_content_type=research), the front-end automatically renders it full viewport width — breaking out of the body column. The body column is otherwise capped at col-lg-9 (with the optional 3-col TOC offset), which is too narrow for charts or video embeds. No editor toggle needed: detection happens in render.php (is_singular('statewatch_article') + has_term('research', 'sw_content_type')) and adds a blk-embed-iframe--research-full modifier class. On any other post type / page the block stays inside its container as usual.

Files: src/blocks-acf/embed-iframe/{config.php,render.php,view.ts,style.scss} and views/blocks-acf/embed-iframe/template.twig.

6.4 Calls to action & forms

accordions

Purpose: A title + paragraph on the left, expandable Q&A list on the right.

Where it is used: FAQ-style sections on About, Donate, Work with us pages.

Fields:

Front-end (Figma — section view):

accordions-wide

Purpose: Same as accordions but with a single-column, full-width layout — title above, accordion list below. No supporting button column.

Where it is used: When the accordion list is the primary content of the section.

Fields:

Front-end (Figma — section view):

cta-banner

Purpose: Small inline call-to-action card. Title + short text + a single dark-arrow link button. Designed to be embedded in narrow columns or as a footer accent, not as a full-width section.

Where it is used: Inside support-cta, in narrow page columns, or as a footer accent on landing pages.

Fields:

Front-end (Figma — section view):

support-cta

Purpose: Two-row support / donate section. Top row: title left, text + multiple buttons right. Bottom row: tabbed embed area for Stripe / Brevo / similar widgets.

Where it is used: Donate page, About page bottom.

Fields:

Front-end (Figma — section view):

contact-form

Purpose: The contact form on the Contact page. Hard-coded fields: Name (required), Organisation, Email (required), Message (required). Submits via AJAX.

Where it is used: Contact page.

Fields (only the heading area is editable; the form itself is fixed):

Form fields (fixed in code — see views/blocks-acf/contact-form/template.twig): name, organisation, Email (email), message. Includes a hidden honeypot (hp_input) and a nonce + timestamp for spam prevention. Submissions go through src/php/Ajax/Contact.php.

Where submissions go: the address stored in the ACF Options field Contact email (contact_email). If empty or invalid, the form falls back to get_option('admin_email'). Submissions are sent only by email — there is no database log.

Front-end (Figma — section view):

contact-columns

Purpose: A row of up to 4 columns each with title + body + a list of links. Links can be plain links, arrow-CTAs, or pop-up triggers (modal opens with extra info).

Where it is used: Contact page (below the form), other contact / partners pages.

Fields:

Each column_links row:

Front-end (Figma — section view):

6.5 Topical navigation

focus-areas

Purpose: Long horizontal list of all focus areas as link labels. Hover applies the focus area's brand colour.

Where it is used: Homepage (full list) and other broad-overview pages.

Fields:

Auto-loaded data: the focus area list is queried by the block's render.php from sw_focus_area posts. Editors do not add focus areas through this block — manage them in the Focus Areas CPT.

Per-focus-area visual customisation (set on the Focus Area post itself): - color — hover background colour (CSS custom property --label-hover-color). - is_light — flag toggling text colour to dark on light backgrounds (boolean ACF field on sw_focus_area).

Front-end (Figma — full section: title + label list):

focus-areas-tiles

Purpose: Three-column tile grid of focus areas with title + excerpt per tile. Lighter than focus-areas, used as a directory.

Where it is used: Our work page main listing.

Fields:

Auto-loaded data: focus_areas array (from render.php), each with title, link, excerpt, color, is_light.

Hover behaviour: the tile heading uses the same weight as the focus-areas button labels on the homepage (.text-headline-6 / 400). The excerpt is hidden by default and revealed on hover at full opacity in solid white (or solid black on tiles flagged is_light) — never as a tint of the card's brand colour. Source: src/blocks-acf/focus-areas-tiles/style.scss.

Front-end (Figma — section view):

6.6 Search & curated lists

search

Purpose: The full-page search experience: search input, multi-filter dropdowns (Type / Topic / Country / Institution / Date range), and a results area populated via AJAX.

Where it is used: /search/ page.

Fields: None. This block has no editor-facing fields; it is a fully-rendered widget.

Auto-loaded data (from render.php): - type_terms — terms from sw_content_type - topic_terms — sw_topic - country_terms — sw_org - institution_terms — sw_institution - filter_nonce — nonce for the AJAX endpoint - ajax_url — admin-ajax.php - Date pickers use Flatpickr (initialised in view.ts).

AJAX backend: src/php/Ajax/SearchFilter.php. Returns rendered HTML cards.

Front-end (Figma — three states of the search block):

related-documentation

Purpose: A list of related documents (manually curated by the editor) shown at the bottom of an article or research post.

Where it is used: Inside individual research / analysis posts where the editor wants to surface specific documents.

Fields:

Front-end (Figma — section view):

6.7 Listings (auto-queried)

Listing blocks query statewatch_article (or person / job) and render a list of cards. Most have only a title editable field — the actual content is auto-loaded from the matching CPT.

latest-articles

Purpose: The homepage's "Latest articles" section. Shows the 2 most recent articles as large cards on the left, plus up to 7 more as small cards on the right (sticky on desktop).

Where it is used: Homepage.

Fields:

Auto-query (from render.php): statewatch_article posts with sw_content_type term ID 1160 (Articles → News), max 10, ordered by date DESC. The first 2 go to the left column, the next 7 to the right.

Front-end (Figma — full row: left tiles + right scrolling list):

all-articles

Purpose: Full Articles archive with filter dropdowns (Type / Topic / Country) and AJAX-driven pagination.

Where it is used: /articles/ page.

Fields:

Auto-loaded data (from render.php): - type_terms — children of term ID 1160 in sw_content_type (i.e. News, Analyses, etc.) - topic_terms — sw_topic - country_terms — sw_org - filter_nonce, ajax_url

AJAX backend: src/php/Ajax/ArticleFilter.php. Action filter_articles. Returns paginated HTML cards (partials/post-card-small.twig).

Front-end (Figma — full block view):

latest-resarch (slug misspelled — do not rename)

Purpose: Homepage "Latest research" section.

Where it is used: Homepage.

Fields:

Auto-query: statewatch_article posts with sw_content_type = Research, ordered by date DESC. The limit is set in the block's render.php.

⚠ The slug is latest-resarch (sic — "resarch" instead of "research"). It is preserved as-is to avoid breaking existing block references in saved page content. Do not rename without a database migration.

all-research

Purpose: Full Research archive with two sections: Active on top, Archived below (driven by sw_status).

Where it is used: /research/ page.

Fields:

Auto-loaded data: Active vs. archived split is rendered server-side. AJAX backend: src/php/Ajax/ResearchFilter.php.

Front-end (Figma — full block view):

all-documents

Purpose: Full Documents archive with filter dropdowns + Flatpickr date-range picker.

Where it is used: /documents/ page.

Fields:

Auto-loaded data: Document-relevant taxonomies (sw_content_type Documents subtree, plus institution / legislation / keyword filters). Date range: filters by Date (_swxi_sdp_document_datetime).

AJAX backend: src/php/Ajax/DocumentFilter.php (action: filter_documents, nonce: documents_filter_nonce).

Front-end (Figma — full block view):

all-events

Purpose: Events page with two sections — Upcoming (sorted ascending) and Past (sorted descending, badged with "Archive", grey background).

Where it is used: /events/ page.

Fields:

Auto-query: statewatch_article with sw_content_type = Events. The split into upcoming / past is by Event date (_swxi_event_date) (today's date as pivot).

Front-end (Figma — full block view):

upcoming-events

Purpose: Homepage "Upcoming events" section — only future events, sorted ascending.

Where it is used: Homepage.

Fields:

Auto-query: Same as all-events, restricted to events where _swxi_event_date >= today, sorted ASC.

Front-end (Figma — full section, header + event tiles):

annual-reports

Purpose: A grid/list of annual report posts.

Where it is used: Annual reports landing page (or the homepage "About" section).

Fields:

Auto-query: statewatch_article with sw_content_type = Annual Reports.

Front-end (Figma): No dedicated annual-reports listing in the Figma source. The block reuses the same card layout as Research — see all-research above.

jobs

Purpose: List of currently-open job openings.

Where it is used: Work with us page.

Fields:

Auto-query: job CPT with post_status: publish, posts_per_page: -1, ordered by menu_order ASC. Closed jobs (status field = closed OR closed_date < today) are filtered out client-side.

Front-end (Figma — full block view, with hero header above):

people

Purpose: Filterable team page. Shows people grouped by person-category. Staff tab is active by default; other categories are tabs.

Where it is used: About us page (team section).

Fields:

Auto-loaded data: categories (sorted: Staff first, then alphabetical), persons (initial set = first category, ordered by menu_order), filter_nonce, ajax_url.

AJAX backend: src/php/Ajax/PeopleFilter.php. Switching tabs fetches the next category's persons.

Front-end (Figma — full block view, with hero header and title-text-image above):

7. Single post layouts

Single page layouts are picked by routing logic in the PHP layer (single-*.php), then rendered by Twig templates in views/. The table below summarises the routing:

Each layout below documents what the editor controls, what is auto-rendered, and where each piece of data comes from.

7.1 Article single

The article single layout is composed of three rows:

1. Top row — back link (col-3) + badge + H1 + optional Download Report button (col-9).
2. Meta + thumbnail row — left col-3 = sidebar metadata box; right col-9 = featured image (desktop only).
3. Content row — left col-3 = sticky side menu (table of contents); right col-9 = the post's Gutenberg content + author block + tags + related sections.

Row 1 — Top: badge, title, download

Row 2 — Meta sidebar (left col-3)

The metadata sidebar lists only the rows whose source field is non-empty. Each label and value is rendered exactly as written in the admin.

Row 2 — Thumbnail (right col-9, desktop only)

The post's Featured image is rendered with the large size at full column width. If no featured image is set, a placeholder (assets/images/placeholder.png) is shown. On mobile the thumbnail appears in row 1 (above the meta sidebar) and this column is hidden.

Hide the featured image per post via the Display options → Hide featured image (hide_featured_image) ACF toggle. When enabled, both the desktop hero column and the mobile hero strip are suppressed (the placeholder fallback too) — so posts that lead with an embed, chart, or pull quote can show that content right under the title without an empty placeholder above. Available on Articles and Research; see Section 4.1 for the field definition.

Row 3 — Side menu + Gutenberg content

Left column (col-3) — sticky side menu (table of contents).

The side menu is not an editor field. It is built automatically by initArticleToc() (in app.ts) on every article single page:

1. After the page loads, the script collects every <h2>, <h3> and <h4> inside the article body.
2. Each heading is given a unique id (slugified from its text) so it can be linked.
3. The script renders an <ul> of links inside the side menu nav, indented by heading level.
4. On scroll, the link of the heading currently in view is highlighted (.is-active).
5. Clicking a link smooth-scrolls to the heading.

To control what the side menu shows, the editor simply uses Heading 2 / Heading 3 / Heading 4 in the WYSIWYG of the article-body block (or whichever heading-bearing blocks are in the post). Adding a heading creates a new entry; removing it removes the entry. There is no "exclude this heading from the menu" option.

Right column (col-9) — Gutenberg content.

The article body is a stack of ACF blocks edited in Gutenberg. Each block is a separate, reorderable section of the article. Typical composition:

The visible "boxed" text-style sections that appear inside long-form articles (e.g. paragraphs framed with a subtle border) are not a separate ACF block — they are produced by HTML wrappers inside the WYSIWYG of the article-body block (typically <blockquote> or a styled <div> retained from a Word paste). They render through the .text-content styles applied to every article-body content area.

Footnotes / endnotes

Footnotes are auto-wired by initArticleFootnotes() in app.ts. The mechanism supports both Word-pasted content and manually authored notes. To use them:

1. In the body, where the reference appears, write a numbered link with href="#fn-N" (or href="#_bookmark…" if pasted from Word). The visible text should be the number itself.
2. At the very end of the article, add an ordered list (<ol>) where each <li> is a footnote. Each footnote item must contain at least one external link (http…) — the script uses this to identify the OL as the footnote list (so any other ordered lists you used inside the article are ignored).
3. Save / Update.

On render, the script:

• Wraps every inline reference in <sup> so it renders superscript.
• Assigns IDs fnref-N (inline) and fn-N (in the list).
• Inserts an "Endnotes" heading above the list and adds ↩ back-links to each item.
• On desktop (≥992 px), hovering a reference opens a popover on the right side of the content column showing a preview of the footnote.

If the inline reference count and footnote item count do not match, the surplus inline references stay wired but their popover is empty. Always keep the counts equal.

Author block + tags + related sections (auto-rendered, below the body)

How to populate Related sections (editorial steps):

1. Open the article in the editor.
2. Scroll to the ACF fields panel — find the four fields Related articles, Related research, Related documents, Related events.
3. Each field is a Post Object / Relationship picker. Click and search by post title; click the result to add it.
4. Drag rows to re-order — the front-end shows them in the same order.
5. Save / Update.

Each related section is rendered with its own header partial and a "View all" CTA button at the bottom (the CTA URLs come from theme-options Post Object fields: All articles page, All research page, All documents page, All events page).

Auto-rendered elements (editor cannot override)

• "Back to articles" link — URL pulled from the ACF Options field All articles page (all_articles).
• Article badge text — first leaf sw_content_type term name.
• Sidebar share button (LinkedIn / Mastodon / Bluesky / Threads / WhatsApp).

Front-end (Figma):

Front-end (Figma — version with side menu visible):

Front-end (Figma — Related documents section):

7.2 Document single

Layout: Two columns under a top "back / title / download" row: left col-3 = sticky metadata sidebar, right col-9 = embedded PDF viewer.

What the editor controls (all via ACF _swxi_sdp_* fields — see Section 8.2 for the field-by-field reference):

What is auto-rendered:

• "Back to documents" link.
• "Document" badge (fixed text, not pulled from a taxonomy term).
• "Download document" button.

Front-end (Figma — short title):

Front-end (Figma — long title):

7.3 Event single

Layout: Top row = back link + badge + title. Below: metadata sidebar (Date / Time / Location / Host) + hero image + body content + Add-to-calendar button.

What the editor controls:

Front-end (Figma):

7.4 Research single

Layout: Same skeleton as Article single, with two extras: - Section badges row above the title — pulls from sw_section terms (e.g. Reports, Bulletins). - Optional sidebar TOC — toggled per-post by the Show table-of-contents sidebar (show_navigation) ACF field (in the Research — Sidebar Navigation group). Recommended for long, multi-section research pieces. The TOC is auto-generated from H2 / H3 headings inside the body.

What the editor controls: same as Article single, plus:

Embed (iframe) blocks render full-width on Research singles — see Section 6.3 (embed-iframe) for the editorial workflow. No per-post toggle is needed; full-bleed is automatic on sw_content_type=research.

Front-end (Figma): - -

7.5 Focus Area single

Layout: Coloured-background hero (background colour from focus area's brand colour) with title and a content box overlay. Below: related research + related articles sections.

What the editor controls:

Auto-rendered (related sections):

• Related research and Related articles — statewatch_article posts whose sw_keyword OR sw_topic terms intersect the focus area's Keywords / Topics ACF fields. Each list is paginated independently (?rpage= and ?apage= query parameters).

Front-end (Figma):

7.6 Person single

Layout: Two-column profile. - Mobile order: name + pronunciation + position → image → body → contact. - Desktop: image right (col-5 offset-1) + content left (col-6).

What the editor controls:

Auto-rendered: related articles (where sw_author = this person AND sw_content_type = News) and related research (same author, content type Research). Sourced via WP meta queries in single-person.php.

"Back to about" link: URL is pulled from the ACF Options field About page (about_page) (a Post Object → page).

Front-end (Figma):

7.7 Job single

Layout: Title under back link → divider → two-column row: sticky Apply button (col-3) + meta dl + body content (col-6).

What the editor controls: see Section 4.4 for the full ACF field list. Summary:

Auto-rendered: "Back to our jobs" link (URL from option → our_jobs ACF Link field), and an "Other open jobs" sidebar listing other job posts whose closed_date >= today and status != closed.

Front-end (Figma):

8. Documents — special editing rules

Documents are the most field-heavy content on Statewatch. This section is the field-by-field reference.

8.1 Why documents differ from articles

A Document is not a separate post type — it is a statewatch_article post that satisfies either:

• sw_content_type is set to Documents (or any descendant), OR
• sw_article_source is set to jha-archive (legacy JHA Archive imports).

When single-statewatch_article.php detects either condition, it routes to views/single-document.twig instead of the regular Article layout. That layout swaps the body for an embedded PDF viewer and replaces the article meta block with a document metadata sidebar.

Implication for editors: if you want to convert a regular article into a Document-style page, just change its Content type to Documents and add the PDF — the layout switches automatically.

8.2 The _swxi_sdp_* fields explained

Documents use ACF fields prefixed with _swxi_sdp_ (Statewatch Document Page) and, for Events, _swxi_event_. They are stored as post meta and read directly with get_post_meta() in the templates — not via Timber's post.meta(), because ACF interferes with underscore-prefixed keys when read through Timber.

For each field below: the meta key, the ACF admin label (if it differs), what it stores, and where it surfaces on the front-end.

Re-import behaviour: the XML Importer deduplicates by Umbraco ID (stored in cms_article_id meta — see Section 12). On re-import, depending on the chosen mode, these fields can be overwritten with the values from the source XML. If you have manually edited a _swxi_sdp_* field and a re-import is scheduled, your edit may be lost..

8.3 Editing a document step by step

1. Open the document. Statewatch → All Articles. Filter by content type Documents if needed.
2. Click the document title to open the editor.
3. In the post body (Gutenberg) — leave it empty for documents; the body is the PDF viewer, not Gutenberg blocks. (If there is content here, it was added by mistake — clean it out unless you specifically want intro text above the PDF, in which case article-body is the right block.)
4. Scroll to the ACF fields panel (under Gutenberg or in a meta box, depending on the field group's position). Update:
5. PDF → upload or replace the file via the media picker.
6. Date / Document number / Classification / Author / Addressee / Publisher → fill or correct.
7. Right sidebar — verify Content type is Documents (or one of its children).
8. Right sidebar — verify Status is Active (or Archived if older).
9. Update keywords / topics / orgs / institutions as appropriate.
10. Click Update (top right).
11. Open the post URL in a new tab to verify the front-end renders correctly:
12. PDF download button works.
13. PDF viewer loads.
14. Sidebar shows all the fields you filled.

` fields filled. Annotate each field with its meta key.*

8.4 Where each field appears on the front-end

Until this annotated screenshot is produced, use Section 8.2 — the table maps every meta key to its front-end location.

9. Authors — assigning posts and where they appear

⚠ Important: authorship on Statewatch is not the standard WordPress Author dropdown. It is the ACF Post Object field Author (sw_author), which links the article to a person CPT post. Read this section carefully — it is the most common source of confusion for new editors.

9.1 Setting the post author

Step by step:

1. Open the article in the editor.
2. Scroll to the ACF fields panel (below Gutenberg or in a meta box).
3. Find the Author field (key: Author (sw_author), type: ACF Post Object → person).
4. Click and search for the person by name. The dropdown queries published person posts.
5. Save / Update.

The person must already exist as a person CPT post. If their name does not appear:

• People → All People — verify the person is published (not draft).
• If they are not in the system at all: People → Add New. Create the post with at least: title (full name), featured image, ACF fields position, email (optional), linkedin (optional), and person-category taxonomy.
• Return to the article and search again.

Do NOT use the WordPress Document → Author dropdown in the right sidebar. That field stores the WordPress user who created the post (used internally for permission checks). It is not displayed on the front-end of the Statewatch theme. Editors who try to "set the author" through the WP sidebar end up with an article that displays no byline at all.

9.2 Multiple / co-authors

The current site does not appear to have a Co-Authors Plus plugin or a multi-author repeater. The Author (sw_author) field is a single Post Object — only one person per article.

single-person.php queries articles using both single-value and serialised-array forms of the Author (sw_author) meta (compare = NUMERIC and compare LIKE '"123"'), so the field accepts both single Post Object and multi-select repeater modes. Whichever mode is currently active is set in Custom Fields → Field Groups → Article.

If multiple authors are needed editorially, the workaround is to put the additional names in the body text (e.g. "By Alice Smith and Bob Jones") until the schema is extended.

9.3 Where the author is displayed on the front-end

The author byline (name + photo + position) surfaces in:

What the byline contains:

• Person's name (post title)
• Position (from ACF Position (position))
• Profile photo (post featured image)
• Click target: /person/{slug}/

9.4 Author profile pages

Each person post has its own URL at /person/{slug}/. The page shows:

• Name (post title), pronunciation, position
• Profile photo
• Bio (post content)
• Email + LinkedIn icons
• Related news articles — statewatch_article posts where sw_author = this person AND sw_content_type = News
• Related research — same with sw_content_type = Research

The "back to about" link at the top of the profile is configurable via the theme options page (ACF Link field About page (about_page)).

The standard WordPress author archive (/author/{user-slug}/) is not used by this theme and may render an empty page. Editors should never link to it.

10. Media library

10.1 Image requirements

Accepted source formats: JPG, PNG. Use JPG for photographic content (smaller), PNG only when transparency is needed.

SVG: uploads of SVG files are enabled via the svg-support plugin. Use sparingly — only for icons/logos, never for content images.

File naming: lowercase, hyphen-separated, descriptive (e.g. frontex-budget-2025-graph.png, not IMG_4321.PNG). The slug is what appears in the URL of the attachment.

10.2 Automatic AVIF / WebP generation

When you upload an image, the theme triggers a background AJAX handler that produces:

• WebP version of every WordPress thumbnail size (medium, large, full, plus the theme's custom sizes)
• AVIF version of the same

These are stored next to the original file (e.g. image.jpg, image.webp, image.avif).

The views/partials/image.twig partial then outputs a <picture> element with <source type="image/avif">, <source type="image/webp">, and a fallback <img>. Modern browsers pick AVIF (~30% smaller than JPG); older browsers fall back gracefully.

If WebP/AVIF is not generated for an upload (you can verify by checking the file alongside the original in the Media → Library):

• Re-upload the image. The handler re-runs.
• As an emergency, the site still serves the JPG/PNG fallback — nothing breaks visually.

10.3 Alt text and accessibility

• Always fill the Alt text field on every uploaded image. It is read by screen readers and used for SEO.
• The alt text should describe the image's content in context. Bad: "Photo of building". Good: "European Council building in Brussels at dusk".
• For purely decorative images (e.g. an abstract pattern as a section divider): leave alt empty AND add role="presentation" if you have HTML access. Filling alt with junk is worse than leaving it empty.
• Title field is rarely necessary; alt is the priority.

10.4 PDF uploads (for documents)

PDFs for Document posts (Section 8) are uploaded via the ACF media picker on the PDF (_swxi_sdp_pdf_attachment_id) field, not via the WP featured image control.

Steps:

1. In the article editor, scroll to the PDF / Attachment ACF field.
2. Click Add File → either select an existing file from the media library or upload a new one.
3. Save / Update the post.
4. The single-document layout's "Download document" button and embedded viewer will pick up the new PDF on the next page load.

File size: PDFs over the host's PHP upload_max_filesize will fail. For very large reports, split or compress before upload.

File naming: the original filename becomes part of the URL — use clean names (e.g. 9375-98-frontex-mandate.pdf, not Scan_2024-12-19__final_v3 (1).pdf).

11. Forms & newsletter

11.1 Contact form

Block: contact-form (Section 6.3) — only appears on the Contact page in the standard build.

Backend: src/php/Ajax/Contact.php. Action: send_contact_form. Nonce: form_contact_nonce.

Where submissions go:

• Recipient email is read from the ACF Options field Contact email (contact_email).
• If Contact email (contact_email) is missing or invalid, the form falls back to the WordPress site admin email (get_option('admin_email')).
• No database log of submissions — only email. If the recipient inbox is broken, submissions are silently lost. Recommend forwarding Contact email (contact_email) to a shared mailbox.

Submitted fields:

Anti-spam: - Honeypot field hp_input — hidden from humans, filled by bots → silent reject. - Timestamp _ts — submissions faster than 2 seconds are rejected. - Flood throttle — Contact.php calls set_transient($key, 1, 1) (1-second TTL) per submission, gating the next request from the same IP for that window.

Editor todo if mail breaks:

1. Open Theme Options → ACF options page (the one with the Brevo settings).
2. Verify Contact email field has a working email address.
3. Send a test submission from the live site.
4. If the test does not arrive: the issue is at the SMTP / mail-relay layer, not the form. Escalate to dev.

11.2 Newsletter (Brevo)

Where it lives in admin: Newsletter & API in the WP sidebar (top-level menu, position 80, icon dashicons-email). Configured by src/php/Settings/BrevoOptions.php.

Settings fields (verified in code):

There is no "double opt-in" toggle in the current settings page. Whether subscribers go through Brevo's double opt-in is configured on the Brevo side (in Brevo's Marketing settings for the list).

How subscriptions flow:

1. User submits the newsletter form on the front-end (typically in the footer or as a CTA block).
2. AJAX action newsletter_subscribe (handler: src/php/Ajax/Newsletter.php) validates the email, runs anti-spam (honeypot + timestamp).
3. The handler POSTs to https://api.brevo.com/v3/contacts with the configured API key + list ID and updateEnabled: true (so re-submitting the same email refreshes the contact rather than failing).
4. Brevo handles the rest (welcome email, double opt-in if enabled).

Editor / admin todo if subscriptions stop working:

• Verify Brevo API key (brevo_api_key) is filled. If empty, the handler logs a warning and shows the user a generic success message — the contact is silently dropped.
• Verify Brevo contact list ID (brevo_list_id) matches an active list in your Brevo dashboard.
• Test a subscription from an incognito window and check whether the contact appears in Brevo's contact list within ~1 minute.
• Logs land in wp-content/debug.log (search for "Newsletter Brevo error").

12. Statewatch XML Importer — for administrators

Scope of this section: how to use the importer day-to-day and how Umbraco data maps onto WordPress objects so editors know what to change vs. leave alone. Migration internals (parser, retry logic, Excel index) are out of scope — see wp-content/plugins/statewatch-xml-importer/IMPORT-GUIDE.md if you need them.

12.1 What it is and what it does

The Statewatch XML Importer (plugin namespace SWXI) is a custom WordPress plugin that imports articles from the old Statewatch Umbraco CMS into WordPress. It was built for the migration in late 2025 and is now used for incremental updates and corrections — not for the bulk one-time load (which is already complete).

Three Umbraco document types end up in one WordPress post type:

The importer is idempotent: running it twice on the same data does not produce duplicates. Deduplication key: the original Umbraco ID, stored in WordPress as a post meta field (the cms_article_id key). If a post with that meta value already exists, the importer either updates it or skips it depending on mode.

12.2 Umbraco → WordPress mapping (cheat sheet)

This is the one cheat sheet to keep open when answering editorial questions about imported content.

12.3 Editing imported content — what is safe vs not

✅ Safe to edit (these are why editors have the admin):

• Post title (display version)
• Post content / Gutenberg blocks
• Post excerpt
• Featured image
• All _swxi_sdp_* and _swxi_event_* ACF fields (Section 8.2)
• Taxonomy assignments: sw_content_type, sw_status, sw_keyword, sw_topic, sw_org, sw_section, sw_institution, sw_legislation
• Author (Author (sw_author) ACF field, Section 9)

⚠ Avoid editing unless you really mean it:

• sw_article_source — changing this can flip the front-end layout (jha-archive → Document layout etc.).
• PDF (_swxi_sdp_pdf_attachment_id) if a PDF is already correct — replacing it removes the original from view (it stays in Media library, but the article points at the new one).

❌ Never edit by hand:

• The cms_article_id meta. It is the deduplication key against re-imports. If you change or remove it, the next import will create a duplicate of this article instead of updating it. (Hidden in standard admin views; only visible if a custom-fields plugin is configured to show it.)

12.4 Re-running an import — what gets overwritten

When the importer encounters an Umbraco ID it has seen before, the behaviour depends on the mode chosen:

Editorial implication: if you have manually edited a _swxi_sdp_* field (e.g. corrected a typo in the document author), and someone runs an Update import that re-syncs the same record from Umbraco, your correction is lost. Coordinate update imports with the editorial team.

12.5 The two commands you need: import-structure then import

The importer has two distinct phases. They must be run in this order:

1. import-structure — populates the sw_section taxonomy with the Umbraco folder hierarchy. Reads the structure analysis file and creates ~527 section terms with parent/child relationships. This only needs to run once (or after structural changes in the source). Without it, individual article imports cannot place articles into sections, and URLs end up flat.
2. import — imports the articles themselves, assigning them to the section terms created in step 1.

Worked example (WP-CLI in a Local Site Shell):

# Step 1 — populate sections (run once)
wp swxi import-structure

# Step 2 — pick what to import. Examples:

# Test: 5 articles, no media, dry run
wp swxi import --type=CmsArticle --limit=5 --skip-media --dry-run

# Real run, 50 newest CmsArticles, with images and PDFs
wp swxi import --type=CmsArticle --limit=50

# JHA Archive (always include media — they are the documents)
wp swxi import --type=JhaArticle --limit=20

# Update mode (CAREFUL — overwrites editor edits)
wp swxi import --type=CmsArticle --limit=10 --update

12.6 Where to access the importer

There are three interfaces. Pick by audience:

Admin UI flow (recommended for editors):

1. Tools → Import Articles
2. Select Article Type (CmsArticle, JhaArticle, DBArticle).
3. Set Number of Articles (1–100).
4. Tick Skip Media for fast tests; untick when you actually want PDFs/images.
5. Click Start Import. Wait 30–60 s.
6. Result page lists imported posts with edit links — click through to verify.

Auto-assignment helpers run automatically on every save:

• AutoSectionAssignment — when an editor manually publishes a new article without ticking any Sections terms, the plugin assigns News → {Year} → {Month} based on publish date.
• AutoContentTypeAssignment — when Add New is clicked from a custom menu link with ?swxi_content_type=..., the plugin pre-selects the Content type taxonomy on save.

These run only on first save, never on re-edit, and never if the editor has manually selected sections / content type. They are why "everything just works" when an editor adds a brand-new news article.

12.7 Excluded content (/statewatch-database/)

About 22,960 records under the /statewatch-database/ URL prefix were intentionally excluded from migration. These are legacy database entries (mostly DBArticle) that the editorial team determined were either obsolete, duplicative, or out of scope for the new site.

If an editor needs to reintroduce one of these records:

• Coordinate with the technical lead.
• The original Umbraco data is preserved (the importer can target individual records by ID).
• Once decided, an admin runs a targeted import of that single record using the standalone CLI.

Do not try to re-enable the bulk /statewatch-database/ import — the exclusion is intentional and reversing it floods the WordPress search with low-quality content.

13. Common editorial workflows (recipes)

Each recipe ends with a Verify on the front-end checklist — always do it before declaring the job done.

13.1 Publish a News article

1. Articles → Add New (the Articles sidebar item filters statewatch_article by sw_content_type=news, and Add New under it pre-applies the News term). The unfiltered list is at All Posts.
2. Title — the headline. Aim for 6–12 words.
3. Featured image — right sidebar → Featured image. Recommended 1200 × 800 px.
4. Body — Gutenberg editor:
5. Add article-body block. Set Show sidebar on if the article has H2/H3 sections totalling more than ~600 words.
6. Add pull-quote blocks where you want big quotes (Section 6.3).
7. Add related-documentation block at the bottom if you want to surface specific PDFs.
8. Right sidebar — Document panel:
9. Permalink — let WP generate it from the title; tweak the slug if needed (the URL will become /news/{year}/{month}/{slug}/).
10. Right sidebar — taxonomies:
11. Content Types — tick Articles → News.
12. Status — leave on Active.
13. Statewatch Keywords — pick existing terms (autocomplete) or add new (,-separated).
14. Statewatch Topics / Statewatch Organisations — same.
15. Sections — leave empty; auto-assignment will set News → Year → Month based on publish date (Section 12.6).
16. ACF fields panel:
17. Author — search for the person. Must already exist as a person post (Section 9.1).
18. Publish.

Verify on the front-end:

• [ ] Open the new URL — it should be /news/{year}/{month}/{slug}/.
• [ ] Title renders as H1.
• [ ] Author byline (with photo + position) appears under the title.
• [ ] Tags appear at the bottom.
• [ ] Article appears at the top of /articles/.
• [ ] Article appears in the Latest articles section on the homepage.

13.2 Add a Document with PDF

1. Statewatch → Add New.
2. Title — short display title (the long official title goes in Full title (_swxi_sdp_title), see step 5).
3. Content (Gutenberg) — leave empty. Documents are rendered as PDF viewer + sidebar metadata; no body needed.
4. Right sidebar — taxonomies:
5. Content Types — tick Documents.
6. Status — Active (or Archived for historical documents).
7. Article Sources — leave blank for new natively-created documents; legacy imports are tagged automatically.
8. Statewatch Keywords / Institutions / Legislation — fill as appropriate.
9. ACF fields panel — _swxi_sdp_* fields (Section 8.2):
10. PDF / Attachment — upload the PDF. Use clean lowercase filename.
11. Date — pick the document date.
12. Document number — e.g. 9375/98.
13. Classification — e.g. LIMITE, RESTREINT UE, PUBLIC.
14. Author — institution / drafter (free text).
15. Addressee — to whom (free text).
16. Publisher — issuing body.
17. Full title — the long official title (used as alt H1 if present).
18. Publish.

Verify on the front-end:

• [ ] URL is /jha-archive/{slug}/ (legacy) or /publications/{section}/{slug}/ (new).
• [ ] Page shows two-column layout: sidebar (Date / Author / Addressee / Publisher / Document number / Classification) + PDF viewer.
• [ ] Download document button works.
• [ ] Document appears in /documents/ listing.

13.3 Add an upcoming Event

1. Statewatch → Add New.
2. Title — event name.
3. Featured image — event hero.
4. Body (Gutenberg) — describe the event (article-body block).
5. Right sidebar — taxonomies:
6. Content Types — tick Events.
7. Status — Active.
8. ACF fields panel:
9. Event date (_swxi_event_date) — pick the date. ⚠ Stored as Ymd string (e.g. 20260415). The ACF picker should be configured to output this format.
10. Event location (_swxi_event_location) — free text (e.g. Brussels, Belgium).
11. Time — Event time (_swxi_event_time) meta.
12. Host / Co-host — Host (_swxi_event_host) / Co-host (_swxi_event_cohost) meta.
13. Register link — ACF Link field Register link (external_url) (or Register link (external_link)).
14. Publish.

Verify on the front-end:

• [ ] Event page renders the date / location / host metadata sidebar.
• [ ] Event appears in Upcoming events on the homepage (if its date is future).
• [ ] Event appears in /events/ under Upcoming.

13.4 Move an article to Archived

1. Open the article in the editor.
2. Right sidebar → Status → switch from Active to Archived.
3. Update.

Effect: - Removed from "latest" feeds (homepage, /articles/ first page, etc.). - Still searchable. - For Events and Research: surfaces in the Past / Archived tab of the listing.

Reversible at any time — flip back to Active.

13.5 Add a person to the team page

1. People → Add New.
2. Title — person's full name.
3. Featured image — square portrait, 800 × 800 px+.
4. Content — bio.
5. ACF fields:
6. Pronouns / pronunciation (pronounce) — pronouns / pronunciation hint (optional).
7. Position (position) — job title (e.g. Director, Researcher).
8. LinkedIn (linkedin) — LinkedIn URL.
9. Email (email) — public-facing email (recommend a forwarding alias, not a personal address).
10. Right sidebar — Person Categories: tick Staff (or whichever category applies).
11. Page Attributes (right sidebar) — Order: sets the order within the category. Lower number = earlier.
12. Publish.

Verify on the front-end:

• [ ] Person appears in the About us page → Staff tab (or relevant category tab).
• [ ] Person's profile page renders at /person/{slug}/.
• [ ] Once you assign this person as Author (sw_author) on an article, the article shows up under "Articles by this person" on the profile page.

13.6 Post a job opening

1. Jobs → Add New.
2. Title — job title.
3. Content — full job description.
4. ACF fields:
5. Location (location) — e.g. London / Remote.
6. Type (type) — e.g. Full-time, Contract.
7. Apply link (apply_link) — ACF Link to the application form / mailto.
8. Closing date (closed_date) — closing date in d/m/Y format. ⚠ Strict — see Section 4.4.
9. Status (status) — open / closed. Leave on open.
10. Page Attributes — Order: sets display order on the Work with us page.
11. Publish.

Verify on the front-end:

• [ ] Job appears on /work-with-us/.
• [ ] Apply button works.
• [ ] Closing date renders as e.g. 30 Mar. 2026.

13.7 Create a Focus Area landing page

1. Focus Areas → Add New.
2. Title — the focus area name (e.g. Border externalisation).
3. Excerpt — 1–2 sentence summary; appears in focus-areas-tiles block.
4. Content — full descriptive text (Gutenberg, can include article-body).
5. Featured image — large hero image (1920 × 1200 px+).
6. ACF fields (verified in single-sw_focus_area.php):
7. color — hex/CSS colour for the hero background.
8. is_light — toggle for dark text on light backgrounds.
9. Slug — keep it short and unique; it becomes part of /focus-area/{slug}/.
10. Publish.

Verify on the front-end:

• [ ] Focus area appears as a label on the homepage focus-areas block.
• [ ] Hover applies the chosen colour.
• [ ] Profile page at /focus-area/{slug}/ renders the hero + content box.

13.8 Update the homepage hero

1. Pages → Home → Edit.
2. Click the Hero block (the first block on the page).
3. In the block sidebar:
4. Image — replace with a new background. 2880 × 1620 px source recommended.
5. Featured post — change the linked statewatch_article to the article you want to feature.
6. Update.

Verify on the front-end:

• [ ] Open / in an incognito window (avoid your editing cache).
• [ ] New background image renders. Card on bottom-right shows the new featured article.
• [ ] LCP score on PageSpeed Insights has not regressed (the new image should be optimised).

14. Card components — taxonomy & field mapping

Listing blocks (Section 6.7) and many cross-references (related sections, focus area pages) render content as cards. There are eight distinct card variants on Statewatch — each has its own partial in views/partials/ and consumes a specific subset of the post's fields and taxonomies.

This section is the cheat-sheet: per card type, exactly which post field / taxonomy term shows up where on the visible card.

Tag colours: most card chips read a CSS custom property --tag-color from the term's _sw_color meta (where present), so editors can colour-code keywords/topics/sections term-by-term in Statewatch Keywords / Topics / Sections term editor.

14.1 Article card — large variant

Partial: views/partials/post-card-large.twig Used by: latest-articles (left column, 2 large cards), all-articles, related-articles section under articles, hero block (bottom-right).

Front-end (Figma):

14.2 Article card — small variant

Partial: views/partials/post-card-small.twig Used by: latest-articles (right scrolling column), all-articles filter results, related-articles tile lists.

Source mapping is identical to the large variant. Visual difference: image is on the left (fixed thumbnail), text on the right.

Front-end (Figma):

14.3 Document card

Partial: views/partials/post-card-document.twig Used by: all-documents block, related-documents section under articles, related-documentation block.

Document cards do not show an image, an author, or an excerpt. They are deliberately bibliographic.

Front-end (Figma):

14.4 Research card

Partial: views/partials/post-card-research.twig Used by: latest-resarch, all-research, Our work page, focus-area related-research section.

Front-end (Figma):

14.5 Annual report card

Partial: views/partials/post-card-annual-report.twig Used by: annual-reports block.

Identical layout to the research card, with one difference: the top tag row pulls from sw_content_type (every term assigned to the post) instead of sw_section. Topic chips below still come from sw_topic.

14.6 Event card

Partial: views/partials/event-card.twig Used by: all-events, upcoming-events, related-events section under articles.

The event card is a horizontal four-column row. Past events render with a grey background and an "Archive" badge above the date.

Front-end (Figma):

14.7 Person tile

Partial: views/partials/post-card-person.twig Used by: people block.

The card has no taxonomy chips — person-category is used to filter which persons appear in which people block tab, not to label the card.

Front-end (Figma):

14.8 Job row

Partial: views/partials/job-card.twig Used by: jobs block, "Other open jobs" sidebar on the job single page.

The job card is a single horizontal row — title on the left, location chip in the middle, hand-drawn arrow on the right.

The job's Type, Apply link, and Closing date fields are not shown on the card — they appear on the job single page only.

Front-end (Figma):

14.9 Focus area tile

Used by: focus-areas-tiles block (3-column grid on Our work) and as a colour label in the focus-areas block.

Front-end (Figma):

14.10 At-a-glance: which taxonomy lands where

"—" means the taxonomy is not displayed on that card variant. Some taxonomies (e.g. sw_org, sw_institution, sw_legislation) are only surfaced on the full single-page sidebar, never on cards.

15. Glossary

Appendix A — Field reference (meta keys)

Single flat table of every meta key referenced in this guide, with its source and front-end consumer.

Appendix B — Troubleshooting

End of guide. Last updated 2026-04-28. To regenerate the .docx: pandoc EDITOR-GUIDE.md -o EDITOR-GUIDE.docx --toc --toc-depth=3.