# FAQ Schema - Complete Guide

## 📖 Table of Contents

1. [What is FAQ Schema?](#what-is-faq-schema)
2. [Why Use FAQ Schema?](#why-use-faq-schema)
   - [Search & AI Benefits](#search--ai-benefits)
   - [User Experience Benefits](#user-experience-benefits)
3. [Adding FAQs to Pages](#adding-faqs-to-pages)
4. [Displaying FAQs (Shortcode)](#displaying-faqs-shortcode)
5. [Styling Options](#styling-options)
6. [Drag-and-Drop Reordering](#drag-and-drop-reordering)
7. [Advanced Customization](#advanced-customization)
8. [Best Practices](#best-practices)
9. [Schema Output](#schema-output)
10. [Conflict Management](#conflict-management)
11. [Troubleshooting](#troubleshooting)

---

## What is FAQ Schema?

FAQ Schema (FAQPage structured data) is a special type of markup that tells search engines and AI systems "this page contains frequently asked questions and their answers." It turns your Q&A content into machine-readable data that answer engines, assistants, and other tools can parse reliably.

**One important note up front:** Google restricted FAQ rich results to government and health sites in August 2023, then removed them entirely for all sites on May 7, 2026. Those expandable question dropdowns no longer appear in Google search results for anyone. So the goal of FAQ schema today is *not* to win those dropdowns. Its value now is making your answers machine-readable (for Google's AI Overviews, assistants, and other consumers of structured data) and, through the shortcode, giving your visitors a clean on-page FAQ display.

### What Entity Schema Provides

**Completely free** FAQ schema that competitors charge $99-$299/year for:

✓ **Unlimited FAQs** - Add as many questions as you need, no artificial limits
✓ **Drag-and-Drop Reordering** - Rearrange questions without deleting/recreating
✓ **Multiple Display Styles** - List (the default), accordion, and minimal layouts
✓ **Automatic Theme Colors** - FAQs match your WordPress theme automatically
✓ **Clean Schema Output** - Properly formatted, valid FAQPage JSON-LD
✓ **Conflict Management** - Works with your existing SEO plugin

This is enterprise-level functionality that major SEO plugins put behind paywalls. We believe FAQ schema should be free for everyone.

---

## Why Use FAQ Schema?

### Search & AI Benefits

**1. Machine-Readable Answers for AI and Search**
Structured FAQ data gives search engines and AI systems (Google's AI Overviews, Gemini, ChatGPT, Perplexity, and others) a clean, unambiguous version of your questions and answers. When these systems assemble a response, well-structured Q&A content is far easier for them to parse and represent accurately than the same text buried in prose.

**2. Answer Engines and Voice Assistants**
Virtual assistants and answer engines often pull from structured content. Marking your answers up as FAQPage data makes them easier for these systems to extract and read back accurately.

**3. Support for Question Queries**
People search using questions: "How do I...", "What is...", "Where can I...". Organizing your content as clear questions with direct answers — and marking it up so machines can read it — helps that content surface for these long-tail, high-intent queries.

**4. Valid, Portable Structured Data**
FAQPage is a standard schema.org type. Beyond Google, other search engines, crawlers, and tools understand it. Clean, valid markup means any consumer of structured data reads your content correctly.

**A note on Google rich results:** Google restricted FAQ rich results to government and health sites in 2023, then removed them for all sites in May 2026. Don't add FAQ schema expecting those dropdowns. Add it for the machine-readability and on-page benefits above.

### User Experience Benefits

**1. Quick Answers**
Visitors find information faster without hunting through long pages. This improves satisfaction and time-on-site metrics.

**2. Reduced Bounce Rate**
When users find answers quickly, they're more likely to explore further rather than bounce back to search results.

**3. Trust Building**
Comprehensive FAQs demonstrate expertise and transparency. You're proactively answering concerns before they become objections.

**4. Mobile-Friendly**
Collapsible accordion FAQs work perfectly on mobile devices where space is limited. Users can scan questions and expand only what they need.

---

## Adding FAQs to Pages

### Step 1: Create or Edit a Page/Post

1. Go to **Pages → Add New** (or edit an existing page)
2. Scroll down past the main content editor
3. Find the **FAQ Schema (Entity Schema)** metabox

The metabox appears on all pages and posts automatically. You can add FAQs to any content type.

### Step 2: Add Your First FAQ

You'll see one FAQ field ready to fill in:

**Question Field**
Enter your question exactly as users would ask it. Use natural language.

**Example:**
✓ "How long does shipping take?"
✗ "Shipping timeframes and delivery schedules"

**Answer Field**
Provide a clear, concise answer. You can use basic HTML formatting (bold, italic, lists, links).

**Example:**
```
Standard shipping takes 3-5 business days. Expedited shipping (2-day) is available for $15 at checkout.

Orders placed before 2pm EST ship the same day.
```

### Step 3: Add More FAQs

Click the **+ Add FAQ** button to add additional questions. There's no limit - add as many as needed.

**How many should you add?**
- Homepage: 5-8 FAQs
- Product pages: 3-5 FAQs
- Service pages: 5-10 FAQs
- Dedicated FAQ page: 15-30+ FAQs

### Step 4: Publish or Update

Click **Publish** (for new pages) or **Update** (for existing pages). The schema is now live on your site!

**Important:** The schema is automatically added to your page's HTML, but you still need to add the shortcode (next section) to *display* the FAQs to visitors.

---

## Displaying FAQs (Shortcode)

The FAQ metabox generates the schema, but to show FAQs to visitors, add this shortcode to your page content:

### Basic Usage

```
[entisc_faq]
```

That's it! The shortcode displays all FAQs from the current page's metabox.

### Where It Works

The `[entisc_faq]` shortcode works anywhere you can add shortcodes:

**Page Builders:**
- ✓ Gutenberg (Shortcode block)
- ✓ Elementor (Shortcode widget)
- ✓ Divi (Text module)
- ✓ Beaver Builder (HTML module)
- ✓ WPBakery (Raw HTML)
- ✓ Oxygen (Shortcode element)
- ✓ Bricks (Shortcode element)
- ✓ Spectra (Shortcode block)

**Classic Editor:**
Paste the shortcode directly into your content.

**Custom Templates:**
Use `<?php echo do_shortcode('[entisc_faq]'); ?>` in PHP templates.

### Strategic Placement Ideas

**1. Above the Fold on Service Pages**
Place FAQs near the top to address common objections immediately.

*Example:* Dentist's "Teeth Whitening" page - FAQs about pain, cost, duration right after the main heading.

**2. End of Product Pages**
Address final concerns before the purchase decision.

*Example:* E-commerce product page - FAQs about shipping, returns, sizing after product description.

**3. Dedicated FAQ Page**
Create a comprehensive resource page.

*Example:* /faq/ page with all common questions organized by topic.

**4. Blog Posts**
Add relevant FAQs at the end of how-to articles.

*Example:* "How to Install WordPress" post - FAQs about hosting, databases, troubleshooting.

**5. Landing Pages**
Remove friction from conversion pages.

*Example:* Free trial signup page - FAQs about pricing, cancellation, features.

---

## Styling Options

Entity Schema offers three display styles. All three produce identical, valid FAQPage schema — they differ only in how the FAQs look on the page.

### List Style (Default)

```
[entisc_faq]
```

or explicitly:

```
[entisc_faq style="list"]
```

Every question and answer is shown, fully expanded. This is the default because Google's guidance favors visible content over hidden accordion panels for deep-link snippet eligibility, and fully-visible answers are the friendliest for AI systems and assistants reading your page.

**Best for:**
- Maximum visibility of your answers
- AI and answer-engine readability
- Pages where you want every answer seen without a click

### Accordion Style

```
[entisc_faq style="accordion"]
```

Questions are shown; answers stay hidden until clicked, with a smooth expand/collapse animation.

**Best for:**
- Pages with many FAQs
- Limited vertical space
- Mobile-first designs

### Minimal Style

```
[entisc_faq style="minimal"]
```

A stripped-back layout with lighter styling, for when you want the FAQ content to inherit more of your theme's own look.

**Best for:**
- Tightly themed pages
- Designers who prefer minimal plugin styling

All three styles support automatic theme colors and the manual color overrides described below.

---

## Drag-and-Drop Reordering

**One of our favorite features** - and one most FAQ plugins don't offer.

### The Problem with Other Plugins

Most FAQ plugins make you delete and recreate questions just to change the order. This is frustrating and time-consuming.

### Our Solution

In the FAQ metabox, each question has a **⋮⋮ handle** on the left side.

**To reorder:**
1. Hover over the ⋮⋮ handle
2. Click and drag the FAQ to its new position
3. Drop it where you want it
4. Click **Update** to save

**Your content is preserved** - no copying/pasting, no deleting, no data loss.

### Use Cases

**Add a Missed Question**
Created 10 FAQs but forgot one? Add it at the end, then drag it to the correct position.

**Reorder by Importance**
Put your most important/frequently asked questions first. Rearrange as priorities change.

**A/B Testing Order**
Experiment with different question orders to see what performs better.

**Seasonal Adjustments**
Move holiday shipping questions to the top in December, then reorder in January.

This feature alone saves hours of work if you maintain active FAQ pages.

---

## Advanced Customization

### Automatic Theme Color Matching

Entity Schema automatically detects your WordPress theme's colors and applies them to FAQs. No configuration needed!

**What gets detected:**
- Primary/accent colors
- Background colors
- Text colors
- Hover states (automatically calculated)

**Supported themes:**
- All themes using WordPress Customizer color settings
- All block themes with theme.json color palettes
- Custom themes with standard color settings

**Result:**
Your FAQs look like they were custom-designed for your site.

### Manual Color Override

Want custom colors? Use shortcode attributes:

```
[entisc_faq accent_color="#ff6600" bg_color="#f5f5f5" text_color="#333333"]
```

**Available color attributes:**
- `accent_color` - Primary color (borders, icons)
- `bg_color` - Background color
- `text_color` - Question text color
- `answer_bg` - Answer background color
- `answer_text` - Answer text color

**Example - Brand Colors:**
```
[entisc_faq accent_color="#e74c3c" bg_color="#ecf0f1" text_color="#2c3e50"]
```

All colors use standard hex codes (#RRGGBB format).

---

## Best Practices

### Question Writing Tips

**DO:**

✓ **Use natural language** - "How long does shipping take?" not "Shipping duration"
✓ **Match search queries** - Think about what users type into Google
✓ **Be specific** - "Do you offer same-day delivery in Los Angeles?" not "Do you deliver fast?"
✓ **Front-load keywords** - "WordPress hosting: Do you offer managed WordPress?" not "Do you offer managed WordPress hosting?"
✓ **Keep it under 10 words** - Short questions scan better and work better for voice search

**DON'T:**

✗ **Use jargon** - "What is your SLA?" → "What is your uptime guarantee?"
✗ **Be vague** - "How does pricing work?" → "How much does the basic plan cost?"
✗ **Ask yes/no questions** - "Is shipping free?" → "How much does shipping cost?"
✗ **Use internal terminology** - "What's included in SKU-PRO-001?" → "What features are in the Pro plan?"
✗ **Make them too long** - "I was wondering if you could tell me about..." → Just ask the question

### Answer Writing Tips

**DO:**

✓ **Answer directly first** - "Yes, we ship internationally" then add details
✓ **Keep it concise** - 2-3 sentences is ideal, max 4-5 sentences
✓ **Use simple language** - 8th-grade reading level is perfect
✓ **Include specifics** - Numbers, timeframes, prices when relevant
✓ **Link to details** - "Learn more about our [shipping policy](/shipping)"

**DON'T:**

✗ **Write essays** - Google prefers concise answers (under 300 characters ideal)
✗ **Sell too hard** - Be helpful, not promotional
✗ **Use complex formatting** - Keep it simple (bold, italic, lists okay)
✗ **Leave questions unanswered** - If you ask it, answer it completely

### How Many FAQs?

**Homepage: 5-8 FAQs**
Cover the most common questions new visitors ask. Focus on trust-building (shipping, returns, guarantees).

**Product/Service Pages: 3-7 FAQs**
Address specific concerns about that product/service. Keep it focused.

**Blog Posts: 2-5 FAQs**
Add related questions at the end of how-to articles. Don't overdo it.

**Dedicated FAQ Page: 15-30+ FAQs**
Go comprehensive. Organize into categories if you have 20+.

**Too Few:**
Less than 3 FAQs looks sparse and offers little value to visitors or to the systems reading your structured data.

**Too Many:**
More than 30 on one page can overwhelm users. Consider splitting into categories or multiple pages.

### Organization Tips

**Order by Importance**
Put your most frequently asked questions first. Use analytics and support tickets to identify top questions.

**Group Related Questions**
If you have 10+ FAQs, group them:
- Shipping & Delivery
- Returns & Refunds
- Pricing & Billing
- Technical Support

**Use Multiple Pages**
Don't cram everything onto one FAQ page. Create topic-specific pages:
- `/shipping-faq/` - All shipping questions
- `/pricing-faq/` - All pricing questions
- `/technical-faq/` - All technical questions

**Update Regularly**
Review FAQs quarterly. Add new questions from support tickets, remove outdated answers.

---

## Schema Output

### What Gets Generated

When you add FAQs, Entity Schema automatically generates clean JSON-LD markup. Here's what it looks like:

```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How long does shipping take?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Standard shipping takes 3-5 business days. Expedited shipping (2-day) is available for $15 at checkout."
      }
    },
    {
      "@type": "Question",
      "name": "Do you ship internationally?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes! We ship to over 50 countries. International shipping takes 7-14 business days depending on location."
      }
    }
  ]
}
```

This markup is inserted into your page's `<head>` section automatically. You don't need to do anything - it just works.

### Verifying It Works

**Method 1: View Page Source**

1. Visit the page with FAQs in your browser
2. Right-click anywhere → **View Page Source**
3. Press **Ctrl+F** (Windows) or **Cmd+F** (Mac)
4. Search for: `FAQPage`
5. You should see your FAQ schema in the source code

**Method 2: Schema.org Validator** (Recommended)

Google's Rich Results Test no longer reports FAQ markup (see the note below), so use the Schema.org Validator to confirm your FAQPage data is well-formed:

1. Copy the URL of your FAQ page
2. Go to: [https://validator.schema.org/](https://validator.schema.org/)
3. Paste your URL and click **Run Test**
4. Look for "FAQPage" with its list of Question / acceptedAnswer pairs

**What you'll see:**
- Your FAQPage, with each Question and its answer listed = Valid ✓
- Errors or warnings flagged inline against the offending field ✗

**Errors to fix:**
- "Missing required field: name" - Add a question
- "Missing required field: text" - Add an answer
- Page not reachable - Check your page is published and publicly accessible

### Will Google Show FAQ Rich Results?

**No.** Google restricted FAQ rich results to government and health sites in August 2023, then removed them entirely for all sites on May 7, 2026. Those dropdowns no longer appear for anyone, and the Rich Results Test no longer reports FAQ markup at all.

That does **not** make FAQ schema pointless. Valid FAQPage data still:
- Gives AI systems and answer engines a clean, machine-readable version of your Q&A that's easy to parse and represent accurately
- Is understood by other search engines and tools that consume structured data
- Powers the on-page FAQ display your visitors see via the shortcode

**To get the most from it:**
- Use clear, natural-language questions
- Provide complete, direct answers
- Don't spam keywords
- Keep answers concise (under ~300 characters reads well)
- Make sure the page has good overall quality

---

## Conflict Management

Entity Schema includes automatic conflict management to prevent duplicate FAQ schema if you're using Yoast SEO, Rank Math, or All in One SEO.

### How It Works

When you add FAQs using Entity Schema:

1. **Our plugin generates** FAQPage schema for pages with Entity Schema FAQs
2. **Your SEO plugin** is automatically prevented from outputting duplicate FAQ schema on those pages
3. **Everything else works normally** - Your SEO plugin still handles Article schema, breadcrumbs, etc.

### Enabling Conflict Management

1. Go to **Entity Schema → Conflicts** in your WordPress admin
2. Check the box: **Enable automatic conflict management**
3. Click **Save Conflict Settings**

That's it! The plugins now work together seamlessly.

### What Gets Filtered

Entity Schema filters these schema types from SEO plugins **only on pages with Entity Schema FAQs**:
- FAQPage
- Question

Everything else passes through:
- Article
- BlogPosting
- HowTo
- Video
- Product
- Breadcrumbs

### Manual Control (Advanced)

If you want to use your SEO plugin's FAQ features instead of Entity Schema:
1. Don't add FAQs in the Entity Schema metabox
2. Use your SEO plugin's FAQ blocks/fields
3. Entity Schema won't interfere

You can mix and match on different pages - use Entity Schema FAQs on some pages, SEO plugin FAQs on others.

---

## Troubleshooting

### FAQs Not Displaying on Page

**Problem:** Added FAQs in metabox but they don't show on the page.

**Solution:**
You need to add the `[entisc_faq]` shortcode to your page content. The metabox creates the schema (for search engines) but the shortcode displays the FAQs (for visitors).

**Where to add it:**
- Gutenberg: Add a Shortcode block
- Classic Editor: Paste the shortcode into your content
- Page Builders: Use a shortcode widget/element

---

### Schema Not in Page Source

**Problem:** View source doesn't show any FAQ schema.

**Checklist:**
1. ✓ Did you add at least one FAQ with both question AND answer filled in?
2. ✓ Did you click **Update** or **Publish** after adding FAQs?
3. ✓ Are you viewing the correct page? (Schema only appears on pages with FAQs)
4. ✓ Is your cache cleared? (Try hard refresh: Ctrl+Shift+R)

**Still not working?**
Check for JavaScript errors in your browser console (F12). A plugin conflict might be preventing schema output.

---

### FAQs Look Wrong / Broken Styling

**Problem:** FAQs display but look unstyled or broken.

**Possible causes:**

1. **Theme CSS conflict**
Your theme might have conflicting styles. Try adding custom colors:
```
[entisc_faq accent_color="#0073aa"]
```

2. **JavaScript not loading**
If using accordion style, JavaScript must load for expand/collapse to work. Check browser console for errors.

3. **Page builder stripping styles**
Some page builders strip inline styles. Try adding the shortcode in a plain HTML/Text element instead of a styled container.

**Quick test:**
Switch to a default WordPress theme (Twenty Twenty-Four) temporarily. If FAQs work there, it's a theme conflict.

---

### Validator Says "Invalid Schema"

**Problem:** The Schema.org Validator (or another structured-data checker) flags errors.

**Common errors and fixes:**

**"Missing required field: name"**
→ One of your questions is empty. Fill in all question fields.

**"Missing required field: text"**
→ One of your answers is empty. Fill in all answer fields.

**"Page not reachable" / "Invalid URL"**
→ The validator can't access your page. Make sure:
- Page is published (not draft)
- Site is publicly accessible (not in maintenance mode)
- No robots.txt blocking crawlers

**"Parsing error"**
→ Usually a caching issue. Clear all caches and try again.

---

### FAQ Rich Results Not Showing in Google

**This is expected.** Google retired FAQ rich results (the expandable dropdowns) for general websites in 2023. If you're not a recognized government or health authority, those dropdowns will not appear no matter how valid your markup is — and Google Search Console no longer has an FAQ enhancement report.

**This is not a bug, and your schema is not wasted.** Valid FAQPage data still does its job:
- AI systems and answer engines can read and represent your Q&A accurately
- Other search engines and structured-data tools understand it
- Your visitors see the on-page FAQ display rendered by the `[entisc_faq]` shortcode

If your goal was the SERP dropdowns specifically, that option no longer exists for general sites — from anyone, not just this plugin. Focus instead on clear questions, direct answers, and a good on-page experience.

---

### Accordion Not Expanding (JavaScript Issue)

**Problem:** Click FAQ question but nothing happens.

**Causes:**

1. **jQuery not loaded**
Entity Schema requires jQuery. Make sure another plugin or theme hasn't disabled it.

2. **JavaScript errors**
Check browser console (F12) for errors. Another plugin might be breaking JavaScript site-wide.

3. **JavaScript conflict**
Another plugin may be interfering with the accordion JavaScript. Try disabling other plugins temporarily to identify conflicts.

**Test:**
Disable all other plugins temporarily. If accordion works, you have a plugin conflict.

---

### Need More Help?

**Documentation:**
Visit [entityschema.com/docs](https://entityschema.com/docs/) for more guides.

**Support:**
Contact us at [entityschema.com/support](https://entityschema.com/support) with:
- Your WordPress version
- Theme name and version
- Active plugin list
- Page URL where FAQs should appear
- Screenshot of the issue

**Community:**
Join our user community for tips and tricks from other users.

---

## Summary

Entity Schema gives you **completely free** FAQ schema that competitors charge $99-$299/year for:

✓ Unlimited FAQs on unlimited pages
✓ Drag-and-drop reordering (unique feature!)
✓ List, accordion, and minimal display styles
✓ Automatic theme color matching
✓ Clean, valid FAQPage output
✓ Conflict management with SEO plugins

**Get started:**
1. Add FAQs in the metabox
2. Add `[entisc_faq]` shortcode to your page
3. Verify the markup with the [Schema.org Validator](https://validator.schema.org/)

Note: Google removed FAQ rich results for all sites as of May 2026. FAQ schema today is about machine-readable answers for AI and search plus a clean on-page display — not SERP dropdowns.

**Questions?**
Contact us at [entityschema.com/support](https://entityschema.com/support)

Happy FAQ building! 🎉
