FAQ accordions that crawlers can actually read

The bug: conditionally rendered answers

The default React accordion holds an open state and renders the answer only when it is true. That looks correct in a browser and is wrong in the delivered HTML: the server renders the closed state, so the answers are simply not there. A crawler fetching the page sees a list of questions and no answers.

It gets worse with schema attached. FAQPage markup asserts that the page contains those questions and answers; if the answers only exist after an interaction, the structured data is describing content that is not in the document. That is the kind of mismatch worth fixing whether or not anything ever penalises you for it — the markup is supposed to be a machine-readable copy of what a person sees.

{/* Answer only enters the DOM after a click — invisible to crawlers,
    and the FAQPage schema below now describes text the page lacks. */}
{isOpen && (
  <div className="px-6 pb-4">
    <p>{answer}</p>
  </div>
)}

The fix: native details, answer always mounted

Swap the state machine for <details> and <summary>. The browser handles opening and closing, the answer is in the markup whether the item is open or not, and the component needs no client-side JavaScript at all — which means it also costs nothing against a First Load JS budget.

<details className="tk-fold group ... open:border-tk-teal/30">
  <summary className="flex w-full cursor-pointer items-center justify-between ...">
    <span className="flex-1 font-display text-base font-semibold text-tk-onyx">
      {question}
    </span>
    <svg className="tk-fold-chevron h-5 w-5 shrink-0" aria-hidden="true">…</svg>
  </summary>
  {/* Answer stays mounted (never conditionally rendered) so crawlers and
      FAQPage schema depend on the text being present in the DOM. */}
  <div className="px-6 pb-4 pt-0">
    <p className="font-body text-sm leading-relaxed text-tk-slate/80">{answer}</p>
  </div>
</details>

You get keyboard support, the correct semantics, and the disclosure state exposed to assistive technology without writing any of it. The chevron rotation and the border colour on open are handled with CSS against the open attribute — no state to keep in sync, nothing to hydrate.

Generate the schema from the rendered array

The rule that keeps this honest is mechanical: one array of question and answer pairs, passed both to the component that renders them and to the schema generator. Nobody maintains two copies, so nobody can update one and forget the other — which is how FAQ markup usually ends up describing an older version of the page.

/**
 * Generate FAQPage schema. Only pass Q&A pairs that are rendered visibly on
 * the page, from the same array — markup must match on-page text word for word.
 */
export function generateFAQPageSchema(faqs: FAQItem[]) {
  return {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    mainEntity: faqs.map((faq) => ({
      "@type": "Question",
      name: faq.question,
      acceptedAnswer: { "@type": "Answer", text: faq.answer },
    })),
  }
}

Word-for-word parity is the standard to hold, not approximate agreement. If the visible answer gets edited for tone and the schema keeps the old sentence, you are publishing two versions of your own answer and asking a machine to pick one.

How to check your own pages in a minute

Fetch the page the way a crawler does and search the raw HTML for a distinctive phrase from the middle of a collapsed answer:

curl -s https://example.com/services | grep -c "phrase from a collapsed answer"

Zero means the text is not in the document, whatever the browser shows you — and it is worth running against tabs, modals, and "read more" toggles too, which fail the same way for the same reason. Content behind an interaction is a rendering choice; content that only exists after an interaction is a publishing bug.

The same instinct pays off across a site's structured data generally: schema should be generated from the thing being displayed, never authored alongside it. That is one of the quieter parts of building pages for search and AI-era retrieval, and it costs nothing once the wiring is right.

Questions