PIM Schema (pim-schema)

Reusable structured-data plugin for PIM's WordPress sites (Etch + ACSS stack). Not tied to one client: site-specific bits are settings or filters.

• Plan, decisions, status, next steps: docs/ROADMAP.md. Read it before changing anything.
• Install (once per site): download pim-schema.zip from the latest release, then WP admin → Plugins → Add New → Upload.
• Updates: new releases appear on each site's Plugins screen like any other plugin update (checked about every 12 hours; Dashboard → Updates → Check again to see one right away). One click to update; WordPress auto-updates can be turned on per site if wanted.
• Build / release: ./build.sh (lints + runs the tests, then makes dist/pim-schema.zip); ./release.sh publishes the version as a GitHub release (see CLAUDE.md).
• Tests: php tests/extractor.test.php, php tests/entities.test.php, php tests/post-types.test.php, node tests/faq-parse.test.js. WordPress isn't installed locally; behaviour is verified on a staging site.

FAQ module (v0.1.x)

FAQ block (pim/faq + pim/faq-item), for the block editor

For FAQs written by non-technical editors (blog articles).

1. Write the FAQ in Google Docs: each question as Heading 3, the answer as normal text under it (paragraphs, lists, links). A heading above the questions (e.g. "Frequently Asked Questions") becomes the FAQ title.
2. Copy the section, add an FAQ block, click its paste box, paste. Or paste the text anywhere in the post, select those blocks, Transform → FAQ.
3. Content above the first question stays above the FAQ; a heading above the question level (and what follows) stays below it.

Question detection fallback order: Heading 3 → fully bold paragraphs → most-used heading level (2+ uses) → short paragraphs ending in "?". core/details blocks always convert (summary = question). "Q1." / "1." / "A:" prefixes are removed.

Block options: title + level, questions as plain text or H2–H4 (plain is the accessible default), icon (site default / chevron / plus / triangle / browser default marker / none), one open at a time (native <details name>), include in schema. Items: open by default. Extra classes and anchors via the Advanced panel. FAQ → Group transform turns it back into H3 + paragraphs.

The blocks are dynamic: post content stores only the answer blocks, PHP renders the wrapper. Markup changes never invalidate saved posts.

Front-end markup (same convention as the Etch FAQs):

<div class="wp-block-pim-faq faq" data-faq-icon="chevron">
  <h2 class="faq__title">…</h2>
  <div class="faq__list">
    <details class="wp-block-pim-faq-item faq-item" data-faq>
      <summary class="faq-item__question"><span class="faq-item__icon" aria-hidden="true"></span><span class="faq-item__title">Question</span></summary>
      <div class="faq-item__answer">…answer blocks…</div>
    </details>
  </div>
</div>

Styles (assets/faq.css) are zero-specificity (:where()), neutral (questions inherit the surrounding font, bold), use ACSS spacing variables when present, and expose --pim-faq-* custom properties (gap, divider, question font/size/weight/transform/letter-spacing/colour, icon size/colour, answer gap). Can be turned off in settings.

FAQ schema (any markup)

One FAQPage per page, built from the rendered HTML (so it covers Etch pages, templates, components and loops, plus the block):

• An FAQ item is a <details> with data-faq or one of the classes in Settings → PIM Schema (default faq-item). Question = <summary> text minus aria-hidden parts; answer = the rest, reduced to Google's allowed tags (links keep href, root-relative links become absolute).
• data-faq-schema="off" on an item or any wrapper leaves it out (block option "Include in FAQ schema").
• Duplicate questions on a page are output once.
• Skipped when the page already contains FAQPage JSON-LD (e.g. a Rank Math/Yoast FAQ block).
• Output: `