=== Accordion FAQ – FAQ Schema, Block & Shortcode with Live Search ===
Contributors: maheshpatel
Tags: faq, accordion, faq block, faq schema, faq page
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 4.1.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Accessible FAQ accordions with FAQ schema for Google rich results, a Gutenberg block, shortcodes, live search, and category filters.

== Description ==

**Accordion FAQ** is the fast, accessible way to build an **FAQ page** in WordPress. Create beautiful **accordion FAQs** with the **Gutenberg FAQ block** or a **shortcode**, output valid **FAQ schema** (FAQPage JSON-LD) for Google rich results, and let visitors find answers instantly with **live search** and category filters.

Whether you need a simple frequently-asked-questions section on a landing page, a full searchable knowledge base, or product FAQs on a WooCommerce store, Accordion FAQ gives you a lightweight, SEO-ready toolkit that works with **any theme** — no page builder required, no jQuery, and no bloat.

> **Built for speed and SEO.** Assets load only on pages that actually contain an FAQ, structured data is generated server-side for Google rich results, and every FAQ is fully keyboard accessible out of the box.


= Why choose Accordion FAQ? =

* ✅ **Rank in Google** with valid FAQPage JSON-LD structured data (schema).
* ✅ **Add FAQs anywhere** — Gutenberg block, shortcode, Elementor widget, or WooCommerce product tab.
* ✅ **Truly accessible** — the WAI-ARIA Accordion pattern with full keyboard navigation.
* ✅ **Blazing fast** — conditional asset loading, no jQuery, scalable CSS icons.
* ✅ **Beautiful by default** — six styles, light/dark aware, and fully customizable.
* ✅ **Grows with you** — search, filtering, analytics, voting, visitor submissions, and AI.

= Add FAQs your way =

* **Gutenberg FAQ block** — an “Accordion FAQ” block with a live preview, full-site-editing (FSE) support, and one-click **AI generation** right in the editor.
* **Shortcodes** — drop `[accordion_faq]` (or the classic `[quick_faq]`) into any page, post, or widget.
* **Page builders** — native elements for **Elementor, WPBakery, Divi, Bricks, and Beaver Builder**.
* **WooCommerce tab** — automatically add an FAQ tab to your product pages, with an optional **per-product FAQ picker**.

= FAQ schema for Google rich results =

Accordion FAQ outputs a single, **deduplicated FAQPage JSON-LD** block server-side so search engines can understand your questions and answers. Schema can be toggled globally or per instance — so if an SEO plugin such as Yoast or Rank Math already outputs FAQ schema, you can disable ours in one click to avoid duplicate structured data.

= Accessibility first =

Accordion FAQ implements the full **WAI-ARIA Accordion design pattern**:

* Real `<button>` triggers with `aria-expanded` and `aria-controls`.
* Arrow-key navigation, Home/End support, and visible focus states.
* Honors the visitor’s `prefers-reduced-motion` setting.
* A zero-JavaScript native `<details>`/`<summary>` engine for maximum compatibility.

= Live search & filtering =

* **Live search with highlighting** — visitors filter questions as they type, with matches highlighted.
* **Search autocomplete** — a suggestion dropdown searches your entire FAQ library (REST-backed) and jumps straight to the answer.
* **Category filter tabs** — one-click filtering by FAQ category.
* **Expand / collapse all** — reveal or hide every answer at once.
* **Sticky table of contents** — an optional scroll-spy sidebar for long FAQ pages.
* **Pagination / “Load more”** — keep long libraries snappy.
* **#anchor deep-linking** — link directly to a specific question.

= Styles & design =

* Six styles: **Minimal, Bordered, Filled, Separated, Card, and Modern**.
* Icon styles: **chevron, plus, or arrow**, positioned left or right.
* **Accordion** (one open at a time) or **Toggle** (many open) modes.
* Light/dark aware, styled with CSS variables, and **theme-overridable templates**.

= Engagement & analytics =

* **FAQ analytics** — track views and see your most-viewed FAQs.
* **“Was this helpful?” voting** — collect helpful / not-helpful feedback.
* **Search-term analytics** — see what visitors search for, and which queries return **no results** so you can spot content gaps.
* **Visitor-submitted questions** — let users ask questions from the front end with moderation (pending review), **admin email notifications**, and layered anti-spam (honeypot + timing + rate limiting).
* **Drag-and-drop ordering** — reorder FAQs directly in the admin list.
* **Analytics dashboard** — 30-day trend charts and top-FAQ rankings.

= AI, import & export =

* **AI FAQ generation** — describe a topic and generate ready-to-edit questions and answers using the WordPress core AI client (no third-party API key required).
* **CSV / JSON import & export** — move your FAQ library in and out in seconds.

= Developer friendly =

* Modular, namespaced OOP with a clean autoloader.
* Hooks and filters throughout, plus fully overridable templates.
* A REST API under `accordion-faq/v1` (analytics, server-side search, submissions, AI).

= Perfect for =

* SaaS and product **FAQ pages** and pre-sales questions.
* **Knowledge bases** and support / help centers.
* **WooCommerce** product FAQs and shipping/returns policies.
* Documentation, onboarding, and “Getting started” sections.
* Any page that needs a clean, searchable, SEO-ready **accordion**.

= Shortcodes =

`[accordion_faq]` — the canonical shortcode with full options:
`category`, `term`, `ids`, `style`, `mode`, `engine`, `heading`, `icon`, `orderby`, `order`, `limit`, `open_first`, `search`, `filter`, `expand_all`, `toc`, `per_page`, `schema`, `class`.

Examples:

* `[accordion_faq]` — show all FAQs with your global defaults.
* `[accordion_faq category="billing" mode="toggle" search="1"]` — a searchable “Billing” FAQ where multiple answers can stay open.
* `[accordion_faq ids="12,15,18" style="card" icon="plus"]` — show three specific FAQs in the Card style.
* `[quick_faq id="12"]` — classic shortcode: show FAQs in category (term) `12` (fully backward compatible).
* `[accordion_faq_submit]` — render the front-end “ask a question” submission form.

= FAQ custom post type =

FAQs are stored as a `quick_faq` post type with a `quick_faq_tax` category taxonomy. Add your **question as the post title** and the **answer in the editor**, assign a category, and you’re done. Manual ordering lets you control exactly which question appears first.

== Installation ==

**From your WordPress dashboard**

1. Go to **Plugins → Add New** and search for “Accordion FAQ”.
2. Click **Install Now**, then **Activate**.

**Manual upload**

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate the plugin through the **Plugins** screen in WordPress.

**Create your first FAQ**

1. Add FAQ categories under **FAQs → Categories** (optional but recommended).
2. Add questions under **FAQs → Add New** — the title is the question, the editor holds the answer.
3. Insert the **Accordion FAQ** block, or paste `[accordion_faq]` into any page, post, or widget.
4. Configure global defaults (style, mode, schema, search, and more) under **FAQs → Settings**.

That’s it — your accessible, SEO-ready FAQ is live.

== Frequently Asked Questions ==

= How do I create an FAQ page in WordPress? =
Add your questions under **FAQs → Add New** (title = question, editor = answer), then create a page and insert the **Accordion FAQ** block or the `[accordion_faq]` shortcode. Your questions render as an accessible accordion instantly.

= How do I add FAQ schema for Google rich results? =
FAQ schema is on by default. Accordion FAQ prints a single, deduplicated **FAQPage JSON-LD** block server-side so Google can read your questions and answers. You can disable it globally or per instance under **FAQs → Settings**.

= Will this conflict with the FAQ schema in Yoast or Rank Math? =
No. If your SEO plugin already outputs FAQ schema for a page, simply toggle Accordion FAQ’s schema off (globally or on that instance) so you never ship duplicate structured data.

= Does it work with the Gutenberg block editor? =
Yes. There is a dedicated **Accordion FAQ** block with a live preview, and it supports full-site editing (FSE) themes.

= Does it work with page builders? =
Yes. Accordion FAQ registers native elements for **Elementor, WPBakery, Divi, Bricks, and Beaver Builder**, so you can drop an FAQ into any builder layout with a visual control panel.

= Does it work with WooCommerce? =
Yes. You can automatically add an **FAQ tab** to WooCommerce product pages — perfect for shipping, returns, and pre-sales questions. A **per-product FAQ picker** lets you choose exactly which FAQs (or category) show on each product, with a global fallback.

= Is it compatible with my theme? =
Yes. Accordion FAQ works with virtually any theme. It styles itself with CSS variables, is light/dark aware, and its templates are fully overridable from your theme.

= Will it slow down my website? =
No. CSS and JavaScript load **only** on pages that actually contain an FAQ. There is no jQuery dependency, and the icons are scalable CSS (no image requests).

= Is the accordion accessible? =
Yes. It implements the **WAI-ARIA Accordion pattern** with real button triggers, `aria-expanded`/`aria-controls`, arrow-key navigation, visible focus, and `prefers-reduced-motion` support. A zero-JavaScript native `<details>` engine is also available.

= Does it work without JavaScript? =
Yes. Switch the engine to the native `<details>`/`<summary>` mode for a fully functional, expandable FAQ that needs no JavaScript at all.

= Can visitors submit their own questions? =
Yes. Add the `[accordion_faq_submit]` form so visitors can ask questions. Submissions are held for moderation (pending review) and protected by layered anti-spam (honeypot + timing + rate limiting).

= Can I see which FAQs are most popular? =
Yes. Built-in analytics track FAQ views and “Was this helpful?” votes, with a dashboard showing 30-day trends and your top-performing questions.

= Can I generate FAQs with AI? =
Yes. Describe a topic and Accordion FAQ generates ready-to-edit questions and answers using the WordPress core AI client — no third-party API key required. You review and publish before anything goes live.

= Can I import or export my FAQs? =
Yes. Import and export your entire FAQ library as **CSV or JSON** from the admin tools screen.

= Can I organize FAQs into categories? =
Yes. FAQs use the `quick_faq_tax` taxonomy, so you can group questions by category and show category filter tabs or target a single category in a shortcode/block.

= Can I change the colors and style? =
Yes. Choose from six styles (Minimal, Bordered, Filled, Separated, Card, Modern), pick an icon (chevron, plus, arrow), set its position, and fine-tune the accent color — or override the CSS variables in your theme.

= Is it translation ready? =
Yes. Accordion FAQ is fully internationalized and ready for translation into any language.

= Will my old `[quick_faq]` shortcodes keep working? =
Yes. The `quick_faq` post type, `quick_faq_tax` taxonomy, and `[quick_faq id="…"]` shortcode from earlier versions continue to work unchanged.

== Screenshots ==

1. The accessible FAQ accordion on the front end, with live search and category filter tabs.
2. The Accordion FAQ block in the Gutenberg editor with a live preview.
3. The branded settings screen — global defaults, styles, and schema controls.
4. The analytics dashboard with 30-day view trends and top-FAQ rankings.
5. The “Was this helpful?” voting widget and visitor question submission form.
6. Style gallery — Minimal, Bordered, Filled, Separated, Card, and Modern.

== Changelog ==

= 4.1.0 =
* Added: Search autocomplete — a REST-backed suggestion dropdown that searches your entire FAQ library and jumps to the answer (keyboard accessible).
* Added: Live-search match highlighting on the front end.
* Added: Search-term analytics — see what visitors search for, including queries that return no results (content gaps), on the analytics dashboard.
* Added: Sticky table-of-contents sidebar with scroll-spy for long FAQ pages.
* Added: Pagination / “Load more” for large FAQ libraries (per-page control in Settings).
* Added: Drag-and-drop manual ordering on the FAQ admin list.
* Added: AI FAQ generation directly inside the Gutenberg block editor.
* Added: Per-product FAQ picker for WooCommerce (specific FAQs or a category, with a global fallback).
* Added: Native page-builder elements for WPBakery, Divi, Bricks, and Beaver Builder (joining Elementor).
* Added: Admin email notifications when a visitor submits a question.
* Added: CSV/JSON import now respects an exported `status` column (publish/draft/pending/private).
* Added: Regenerated translation catalog (.pot) with all strings.
* Changed: Analytics tables now upgrade automatically on existing installs (no reactivation required).

= 4.0.0 =
* Added: A completely redesigned, product-grade admin experience — branded dashboard, custom cards, toggle switches, segmented controls and a live preview (no plain WordPress option tables).
* Added: FAQ analytics — view tracking, a “Was this helpful?” voting widget, an analytics dashboard with 30-day charts and top-FAQ rankings.
* Added: Visitor-submitted questions with a shortcode form, moderation (pending status) and layered anti-spam (honeypot + timing + rate limit).
* Added: AI FAQ generation via the WordPress core AI client (no third-party API key required).
* Added: CSV/JSON import and export of your FAQ library.
* Added: Elementor widget and a WooCommerce product FAQ tab.
* Added: A REST API (analytics, server-side search, submissions, AI) under accordion-faq/v1.
* Added: Premium styles (Modern, Card) and icon styles (chevron, plus, arrow).
* Added: Gutenberg block ("Accordion FAQ") with live preview and full-site-editing support.
* Added: FAQPage JSON-LD structured data (server-rendered, deduplicated, toggleable).
* Added: Full keyboard accessibility and the WAI-ARIA Accordion pattern (button triggers, aria-expanded/controls, arrow-key navigation, focus-visible).
* Added: Accordion (one open) and Toggle (many open) modes; open-by-default; native <details> zero-JavaScript engine.
* Added: prefers-reduced-motion support; multiple styles via CSS variables; light/dark aware.
* Added: Live search, category filter tabs, expand/collapse all, and #anchor deep-linking.
* Added: Settings page (global defaults), per-FAQ options (order, default-open, icon), and a canonical `[accordion_faq]` shortcode.
* Added: Theme-overridable templates and a developer hook/filter API.
* Added: Proper internationalization and an opt-in uninstall cleanup.
* Changed: Complete re-architecture to modular, namespaced OOP with an autoloader.
* Changed: Assets now load only on pages that contain an FAQ; jQuery removed; the bitmap arrow replaced with a scalable CSS icon.
* Fixed: Invalid CSS values, cross-instance JavaScript interference, the undefined shortcode "id" default, and unescaped output.
* Backward compatibility: the quick_faq post type, quick_faq_tax taxonomy, and [quick_faq] shortcode continue to work unchanged.

= 3.0.0 =
* Earlier releases provided the FAQ custom post type, taxonomy, and the [quick_faq] accordion shortcode. Detailed history was not maintained prior to 4.0.0.

== Upgrade Notice ==

= 4.1.0 =
Adds search autocomplete & highlighting, search-term analytics, a sticky table of contents, pagination, drag-and-drop ordering, in-editor AI, per-product WooCommerce FAQs, and WPBakery/Divi/Bricks/Beaver builders. Your existing FAQs and shortcodes keep working.

= 4.0.0 =
Major update: a rewritten, faster, fully accessible plugin with a Gutenberg block and FAQ schema. Your existing FAQs, categories, and [quick_faq] shortcode keep working. Please back up and test on staging before updating.