Generate FAQPage JSON-LD schema from Markdown Q&A pairs. Idempotent. No AI required.
Reads a Markdown file with standard Q&A formatting and outputs valid FAQPage JSON-LD schema, ready to embed in your HTML <head>.
Built to scale: process one file or thousands. Idempotent — running the tool twice on the same input produces the same output (no AI nondeterminism, no API costs).
We built this because we ship FAQPage schema on every article and we did not want to depend on a $200/mo content tool for what is, essentially, a regex pass with structured output.
Google removed FAQ rich results from search in May 2026. The schema type itself is not deprecated — only the rich-result rendering. Existing FAQPage markup:
- Still helps Google understand page topical structure
- Is cited 2.3× more by LLMs (Perplexity, ChatGPT, Gemini) than unstructured prose, per Schema App's 2026 extraction-accuracy study
- Is one of the highest-leverage schema types for AEO in our 30-article rollout
If anyone tells you FAQPage is "dead" — they read one headline and missed the actual scope of the deprecation.
npm install -g @surgio-aeo/faq-schema-cli
# or:
npx @surgio-aeo/faq-schema-cli input.mdStandard Markdown Q&A. The CLI recognizes three patterns:
### What is AEO?
AEO stands for Answer Engine Optimization. It is the practice of optimizing content to be cited in AI search responses from ChatGPT, Claude, Perplexity, and Google AI Overviews.
### How is AEO different from SEO?
SEO targets blue-link search results. AEO targets answers generated by LLMs.**Q: What is AEO?**
A: AEO stands for Answer Engine Optimization...faqs:
- question: "What is AEO?"
answer: "AEO stands for Answer Engine Optimization..."
- question: "How is AEO different from SEO?"
answer: "SEO targets blue-link search results..."faq-schema-cli input.mdOutputs:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is AEO?",
"acceptedAnswer": {
"@type": "Answer",
"text": "AEO stands for Answer Engine Optimization. It is the practice of optimizing content to be cited in AI search responses from ChatGPT, Claude, Perplexity, and Google AI Overviews."
}
},
{
"@type": "Question",
"name": "How is AEO different from SEO?",
"acceptedAnswer": {
"@type": "Answer",
"text": "SEO targets blue-link search results. AEO targets answers generated by LLMs."
}
}
]
}
</script>Or, to inject into an HTML file at </head>:
faq-schema-cli --inject input.md article.htmlWrites back to article.html with the schema embedded before </head>. Idempotent — running again finds and replaces the existing schema block, no duplicates.
--inject <html-file> Inject schema into HTML file's <head>
--output <file> Write JSON to file instead of stdout
--no-pretty Minify the output JSON
--validate Just check Q&A formatting, no output
--schema-version Pin to schema.org version (default: latest)
import { generateFaqSchema, injectIntoHtml } from '@surgio-aeo/faq-schema-cli';
const schema = generateFaqSchema(markdownString);
const htmlWithSchema = injectIntoHtml(originalHtml, schema);- uses: surgio-aeo/faq-schema-cli-action@v1
with:
pattern: 'content/articles/**/*.md'
inject: 'public/articles/**/*.html'You can. We use gpt-4o-mini to generate the FAQ content itself (the questions and answers) — that is a creative task that benefits from AI. But once you have the Q&A pairs, the transformation to JSON-LD is deterministic. Using an AI to generate JSON-LD from Q&A pairs is:
- Slower (API roundtrip)
- More expensive (per-token cost adds up at scale)
- Less reliable (AI occasionally hallucinates wrong field names or escapes JSON characters incorrectly)
- Non-reproducible (same input may produce different output on different days)
This CLI is the deterministic, free, fast layer that ships after you have your Q&A pairs.
Anonymous contributions accepted. See CONTRIBUTING.md.
MIT.
faqpage schema-org json-ld seo aeo cli static-site-generator markdown