Skip to main content

Trends, tech news, and tool comparisons.

How to add FAQ schema to a Docusaurus blog (and what it still does)

· 6 min read
Dealpuffin
Proof points and live coupons for early adopters

To add FAQ schema to a Docusaurus blog, write each post's FAQ as a ## Frequently asked questions section with ### question headings, add a remark plugin that exports those pairs from the compiled MDX, and wrap BlogPostPage so it prints them as FAQPage JSON-LD in the page head. You edit one plugin and one wrapper once, and every later post gets the markup from its own text.

Before you spend an afternoon on it, know that Google stopped showing FAQ rich results on 7 May 2026, so the markup no longer earns a visible search feature. This guide shows the build and then covers what is still worth doing. Google's documentation was read on 9 November 2026.

What changed at Google​

Google's Search documentation changelog says the FAQ rich result feature stopped appearing in Google Search starting 7 May 2026, and that the documentation page was removed in June. Since August 2023 the feature had only been shown for well-known government and health sites, so most blogs never saw it anyway.

Valid FAQPage markup is still a schema.org type, and leaving it on a page does no harm. What you should not expect is a rich result. The reasons left to add it are cheap ones: it forces every post to carry clean question-and-answer pairs, and the data sits in a machine-readable form for any tool that wants it. Whether a particular AI search product uses it is not documented, so treat that as unproven. Our post on whether llms.txt helps AI citations takes the same approach to another unproven signal.

The approach in three parts​

Docusaurus has no built-in FAQ field, so the setup has three pieces:

  1. A convention in your Markdown: one ## Frequently asked questions heading, then ### Question? headings, each followed by the answer.
  2. A remark plugin that reads that section at build time and exports it as faqs from the compiled page.
  3. A swizzled wrapper around BlogPostPage that reads faqs and renders the JSON-LD script.

Step 1: write the FAQ in plain Markdown​

## Frequently asked questions

### Does this need a plugin from npm?

No. A short local remark plugin is enough.

### Can I reuse it for docs pages?

Yes. Add the same plugin to the docs preset options.

The text stays in the post body, so readers see the same answers the markup describes. Google's structured data rules have long required that marked-up content be visible on the page, and this approach satisfies that without extra work.

Step 2: the remark plugin​

Create src/remark/blogFaqExport.mjs. The plugin walks the top-level nodes, finds the FAQ heading, collects each ### question and the paragraphs below it, and appends an export const faqs = ... node. A minimal version looks like this:

const FAQ_HEADING = /^(frequently asked questions|faqs?)\b/i;

const text = (node) =>
node.value ?? (node.children ?? []).map(text).join('');

export default function blogFaqExport() {
return (root) => {
const kids = root.children;
const start = kids.findIndex(
(n) => n.type === 'heading' && n.depth === 2 && FAQ_HEADING.test(text(n)),
);
if (start === -1) return;

const faqs = [];
let current = null;
for (const n of kids.slice(start + 1)) {
if (n.type === 'heading' && n.depth <= 2) break;
if (n.type === 'heading' && n.depth === 3) {
current = {question: text(n).trim(), answer: ''};
faqs.push(current);
} else if (current) {
current.answer += ' ' + text(n).trim();
}
}
if (!faqs.length) return;

const json = JSON.stringify(faqs);
root.children.push({
type: 'mdxjsEsm',
value: `export const faqs = JSON.parse(${JSON.stringify(json)});`,
// MDX also needs an estree for the node; see the note below.
});
};
}

The MDX compiler wants a parsed estree on any mdxjsEsm node you inject, so the production version of this plugin builds an ExportNamedDeclaration by hand. If you would rather not write that tree, estree-util-value-to-estree or a call to acorn on the value string produces it. Whichever route you pick, test with a post that has no FAQ section too; the plugin should return without adding anything.

Register it in docusaurus.config.ts for the blog, and for docs if you want it there:

import blogFaqExport from './src/remark/blogFaqExport.mjs';

// inside presets -> classic options
blog: { remarkPlugins: [blogFaqExport] },
docs: { remarkPlugins: [blogFaqExport] },

If you run a second blog instance through @docusaurus/plugin-content-blog, give that instance the same remarkPlugins entry.

Step 3: wrap BlogPostPage and print the JSON-LD​

Run the swizzle command in wrap mode so you keep the original component and only add around it:

npm run swizzle @docusaurus/theme-classic BlogPostPage -- --wrap

Docusaurus's swizzling guide recommends wrapping over ejecting where you can, because a wrapper survives theme upgrades better. Then edit src/theme/BlogPostPage/index.tsx:

import React from 'react';
import Head from '@docusaurus/Head';
import BlogPostPage from '@theme-original/BlogPostPage';

export default function BlogPostPageWrapper(props) {
const faqs = props.content.faqs ?? [];
const faqPage = faqs.length
? {
'@context': 'https://schema.org',
'@type': 'FAQPage',
mainEntity: faqs.map((f) => ({
'@type': 'Question',
name: f.question,
acceptedAnswer: {'@type': 'Answer', text: f.answer},
})),
}
: null;

return (
<>
{faqPage && (
<Head>
<script type="application/ld+json">{JSON.stringify(faqPage)}</script>
</Head>
)}
<BlogPostPage {...props} />
</>
);
}

props.content is the compiled MDX module, which is why a named export from the plugin shows up as content.faqs.

Check that it works​

  1. Run npm run build. A build catches MDX errors from a malformed injected node.
  2. Open build/blog/<your-post>/index.html and search for "@type":"FAQPage". The script should be in the head, and the question count should match your headings.
  3. Paste the live URL into the Schema Markup Validator. Google's Rich Results Test dropped FAQ support in June 2026, so use the schema.org validator for syntax.
  4. Check a post without an FAQ section and confirm it has no FAQPage script.

Mistakes to avoid​

Keep answers to one to three sentences. Long answers are harder to quote and make the JSON-LD bulky. Do not add questions that appear only in the markup. Strip links and formatting down to plain text in the plugin, since the schema text field is plain. And put the FAQ last in the post; the plugin stops at the next ## heading, so a section after it is safe, but a stray ## inside the FAQ cuts it short.

If you are also deciding what to measure on the site, see PostHog vs Plausible vs GA4 for an early-stage SaaS.

Frequently asked questions​

Does Google still show FAQ rich results?​

No. Google's changelog says the FAQ rich result feature stopped appearing in Search starting 7 May 2026. Before that it was limited to well-known government and health sites.

Is FAQPage markup still valid?​

Yes. It is still a schema.org type and validators accept it. It just no longer produces a Google search feature.

Do I need to swizzle Docusaurus to add FAQ schema?​

You need some way to place a script in the page head. Wrapping BlogPostPage is the lightest option; another is a <Head> block inside each MDX file, which means repeating the JSON by hand in every post.

Can the same plugin work for docs pages?​

Yes. Add it to the docs remarkPlugins list and wrap the docs page component the same way, reading content.faqs.