Joomla FAQ section: accordion, schema and what Google shows

Most Joomla sites end up with the same five questions in their contact form. An FAQ on the page answers them before anyone writes in. Joomla has no FAQ feature as such, but the editor and the Schema tab together get you a working FAQ in one article. You can build it by hand as described below, or let our own FAQ module do it when the list grows past a dozen questions.

Option 1: the Accordion button in TinyMCE

Joomla 6 ships TinyMCE with the accordion plugin. In the Advanced toolbar preset there is an Accordion button next to the list buttons. Click it, type the question in the first line and the answer below it. TinyMCE writes standard HTML:

<details class="mce-accordion">
  <summary>Do you ship outside the EU?</summary>
  <p>Yes, to the UK, Norway and Switzerland. Delivery takes 5 to 8 working days.</p>
</details>

Each <details> block opens and closes in the browser without any JavaScript, works with the keyboard and is read out correctly by screen readers. Joomla's text filter does not strip details or summary, so the markup survives saving for every user group that may use the editor.

Don't see the button? Go to System → Plugins → Editor - TinyMCE and check which set your user group gets. Either switch that set to the Advanced preset or drag the Accordion button into its toolbar. With the CodeMirror editor or no editor, paste the HTML above yourself.

Make it look like part of the site

Without styling, a details block is a small triangle and a line of text. A few lines in user.css make it a proper FAQ (see user.css and user.js in Joomla for where that file lives):

details.mce-accordion {
  border-bottom: 1px solid #ddd;
  padding: .75rem 0;
}
details.mce-accordion summary {
  cursor: pointer;
  font-weight: 600;
}
details.mce-accordion[open] summary {
  margin-bottom: .5rem;
}

Why not the Bootstrap accordion that Cassiopeia already has? Its markup needs Bootstrap's collapse script, and Joomla only loads that script when a component or module asks for it. In a plain article the questions then never open. The details element has no such dependency.

Option 2: add FAQPage structured data with the Schema tab

Since Joomla 5 the article edit screen has a Schema tab. There is no FAQ type in the list, but the Custom type takes any JSON-LD you paste in. Check two plugins first, both under System → Plugins:

• System - Schema.org must be enabled; it adds the tab and writes the output.
• Schema.org - Custom must be enabled; it adds Custom to the Schema Type list.

Then open the article, go to the Schema tab, choose Custom and paste the questions into the JSON Code field:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Do you ship outside the EU?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes, to the UK, Norway and Switzerland. Delivery takes 5 to 8 working days."
      }
    },
    {
      "@type": "Question",
      "name": "Can I return a product?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes, within 30 days, unused and in the original box."
      }
    }
  ]
}

On save, the plugin checks that the JSON is valid and that @context is https://schema.org and @type is set. If not, you get the error "The JSON code is not valid or @context or @type is missing." and nothing is stored. Joomla merges the block into the page's @graph next to the Organization and WebSite data from the System - Schema.org plugin. For the other schema types and how that graph is built, see structured data in Joomla 5 and 6 without an extension.

Rules that keep the markup honest

• Every question and answer in the JSON must also be visible on the page, word for word or close to it. Markup for hidden or different text breaks Google's structured data guidelines.
• Use one FAQPage block per page. Don't paste the same FAQ into ten articles.
• When you edit an answer in the article, edit it in the JSON too. This double bookkeeping is the weak spot of the manual method.
• Test the page with the Rich Results Test or the Schema Markup Validator after saving.

What Google does with FAQ markup now

Since August 2023 Google shows FAQ rich results (the expandable questions under a search result) only for well-known government and health sites. A normal company site will not get them, whatever the markup says. The markup is still valid schema.org data that other search engines and AI tools can read, and it costs little once the questions are on the page. Just don't build an FAQ only to win extra space in Google; build it because visitors ask those questions.

When a module is the better fit

The manual method works well for five to ten questions in one article. It gets awkward when the FAQ grows: there is no search, no grouping by subject, and every answer lives twice, once in the text and once in the JSON. Questions that belong on several pages (shipping on every product page, say) have to be copied by hand.

Checklist

• Write the questions people actually send you, not the ones you would like them to ask.
• Build the list with the Accordion button, or paste <details>/<summary> blocks by hand.
• Style it in user.css; skip the Bootstrap accordion in plain articles.
• Enable System - Schema.org and Schema.org - Custom, then paste FAQPage JSON-LD in the Schema tab.
• Keep the JSON in step with the visible answers, one FAQPage per page, and test it.
• More than a dozen questions, or the same FAQ on several pages: use a module such as our own FAQ module.