FAQ Structured Data Component

A reusable MDX component that renders FAQs with optional JSON-LD structured data for SEO. Perfect for both internal documentation (FAQ blocks) and external/public sites (FAQ blocks + structured data for Google rich results).

Features

• Renders FAQs as markdown with proper heading structure
• Optional JSON-LD structured data for SEO (Google FAQ rich results)
• Configurable heading levels and section title
• Toggle structured data for internal vs external documentation
• Collapsible FAQ items with expand/collapse functionality (optional)
• TypeScript types included for better developer experience

Installation

The component is already set up in this repository. For new repositories, see the Setup Guide below.

Usage

Basic Usage

Import the component and use it in any MDX file:

import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

export const faqs = [
  {
    question: 'How do I use the FAQ Structured Data component?',
    answer: 'Simply import the component and pass an array of FAQs. The component will render them as markdown and optionally include structured data for SEO.',
  },
  {
    question: 'Can I use this in blog posts?',
    answer: 'Yes! The component works in any MDX file, including blog posts. Just import it after the frontmatter.',
  },
];

<FAQStructuredData faqs={faqs} />

Internal Documentation (No Structured Data)

For internal documentation where SEO is not needed, disable structured data:

import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

export const faqs = [
  {
    question: 'What is this tool used for?',
    answer: 'This tool is used for internal operations and documentation.',
  },
];

<FAQStructuredData faqs={faqs} includeStructuredData={false} />

External/Public Sites (With Structured Data)

For public-facing sites where SEO is important, enable structured data (default):

import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

export const faqs = [
  {
    question: 'How does your service work?',
    answer: 'Our service helps businesses optimize their marketing technology stack through automated workflows and data analysis.',
  },
];

<FAQStructuredData faqs={faqs} includeStructuredData={true} />

Collapsible FAQs

Enable expand/collapse functionality for FAQ items. When collapsible={true}, FAQs are collapsed by default and can be expanded by clicking the question:

import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

export const faqs = [
  {
    question: 'How do I use the FAQ component?',
    answer: 'Import the component and pass an array of FAQs.',
  },
  {
    question: 'Can FAQs be collapsible?',
    answer: 'Yes! Set collapsible={true} to enable expand/collapse functionality.',
  },
];

<FAQStructuredData faqs={faqs} collapsible={true} />

Custom Configuration

You can customize the heading level, section title, and collapsible behaviour:

import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

<FAQStructuredData 
  faqs={faqs} 
  headingLevel={3}
  title="Common Questions"
  includeStructuredData={true}
  collapsible={true}
/>

Component Props

Prop	Type	Default	Description
faqs	FAQ[]	required	Array of FAQ objects with question and answer properties
includeStructuredData	boolean	true	Whether to include JSON-LD structured data for SEO
headingLevel	1 | 2 | 3 | 4 | 5 | 6	2	Heading level for the FAQ section title (h2, h3, etc.)
title	string	"FAQs"	Custom title for the FAQ section
collapsible	boolean	false	Whether to make FAQ items collapsible. When true, FAQs are collapsed by default and can be expanded by clicking the question

FAQ Object Structure

Each FAQ object should have the following structure:

interface FAQ {
  question: string;  // The question text
  answer: string;    // The answer text (can include markdown)
}

Example Output

The component renders:

1. JSON-LD structured data (if includeStructuredData={true}):

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How do I use this?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "You can use it by importing the component..."
      }
    }
  ]
}
</script>

2. Markdown content (non-collapsible mode):

<h2>FAQs</h2>
<h3>How do I use this?</h3>
<p>You can use it by importing the component...</p>

3. Collapsible FAQ items (when collapsible={true}):

<h2>FAQs</h2>
<div class="faq-item">
  <button class="faq-question-button" aria-expanded="false">
    <span class="faq-question-text">How do I use this?</span>
    <span class="faq-toggle-icon">
      <svg>...</svg>
    </span>
  </button>
  <div class="faq-answer" aria-hidden="true">
    <p>You can use it by importing the component...</p>
  </div>
</div>

Testing Structured Data

After deploying, test your structured data using:

• Google Rich Results Test
• Schema.org Validator

Setup Guide

For New Repositories

1. Copy the component files:

   • docusaurus/src/theme/MDXComponents/FAQStructuredData/index.js
   • docusaurus/src/theme/MDXComponents/FAQStructuredData/types.d.ts

2. Create the directory structure:

mkdir -p docusaurus/src/theme/MDXComponents/FAQStructuredData

3. Copy the files to the new repository

4. Use the component in your MDX files as shown in the Usage section above

Feature Toggle Configuration

To make structured data conditional based on site type, you can add a feature flag to docusaurus.config.ts:

const config: Config = {
  // ... other config
  customFields: {
    features: {
      documentationType: 'internal', // or 'external'
      // ... other feature flags
    },
  },
};

Then in your MDX files, you can conditionally enable structured data:

import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

const {siteConfig} = useDocusaurusContext();
const isInternal = siteConfig.customFields?.features?.documentationType === 'internal';

<FAQStructuredData 
  faqs={faqs} 
  includeStructuredData={!isInternal}
/>

Best Practices

1. Internal Documentation: Set includeStructuredData={false} to avoid unnecessary SEO markup
2. External Sites: Keep includeStructuredData={true} (default) for SEO benefits
3. Collapsible FAQs: Use collapsible={true} for long FAQ lists to improve readability and reduce visual clutter
4. Question Quality: Write clear, concise questions that users would actually search for
5. Answer Quality: Provide comprehensive answers that fully address the question
6. Testing: Always test structured data after deployment to ensure it's valid
7. Accessibility: The component includes proper ARIA attributes for screen readers when using collapsible mode

Related Documentation

• Google FAQ Structured Data Guidelines
• Docusaurus MDX Documentation
• Schema.org FAQPage