How to Add FAQ Blocks and a Table of Contents to Shopify Blog Posts

You read that FAQ sections and jump links help both readers and search engines. Then you opened the Shopify blog post editor and found a text box with headings, bold, a link button, and a table. No FAQ block. No table of contents. Nothing that collapses.

That gap is in the product, not in your knowledge. Shopify's blog editor has never shipped an accordion or a table of contents widget, and the newest generation of themes did not add one.

So the question of how to add FAQ to a Shopify blog post has three real answers, not one, and they differ by how much theme code you are willing to touch. This post walks all three in order of effort, then hands you the anchor-link table of contents you can paste in today. Everything here works on a free theme with no app installed.

One correction first, because it changes what you should expect. If you are building an FAQ block to chase the expandable dropdown in Google search results, that feature no longer exists. It was retired in May 2026. The block is still worth building. The reason is just different from the one most tutorials repeat, and the real reason changes how you write the questions.

Why Shopify's blog editor has neither

Blog posts, pages, product descriptions, and collection descriptions all run through the same rich text editor, built on TinyMCE. Two things in Shopify's documentation for that editor shape everything you can do inside it: a hard 64 KB content limit, and automatic HTML sanitization that corrects markup it considers risky or malformed.

Shopify's own recommendation is to work with those corrections rather than fight them, and to move anything the editor keeps rewriting into your theme code instead. Keep that in mind before you spend an hour on markup the editor will quietly undo.

The toolbar gives you headings, blockquote, bold, italic, underline, lists, indentation, alignment, text color, a table builder, links, images, and video embeds. That is the full list. No accordion, no jump-link generator. There is one more button though, and it is the reason this post has three routes instead of zero: Edit code, which flips the editor into raw HTML view. Shopify documents it for pasting embed codes. It works just as well for a hand-built FAQ block.

The theme side has its own limit. Horizon-era themes are built on nested theme blocks, which is why you can restructure a homepage by dragging. The Blog post section is more fixed. There is an open request in Shopify's developer community asking for blocks to be insertable alongside the article title and content. Until that lands, you cannot drop an FAQ block into the middle of an article the way you can on a landing page.

Two doors, then: the HTML view, or the theme files.

The reason most people add FAQ blocks stopped working in May 2026

This is the part most guides on adding an FAQ section to a blog post have not caught up with, and it matters before you spend an afternoon on implementation.

In August 2023, Google announced it was reducing the visibility of FAQ rich results, limiting them to well-known, authoritative government and health websites. For every commercial store, the expandable dropdown quietly stopped appearing that month.

On May 7, 2026, Google finished the job. FAQ rich results stopped appearing for every site, including the government and health sites that had kept them. The search appearance filter and Rich Results Test support went in June 2026, and Search Console API support goes in August 2026.

What did not change: FAQPage is still a valid schema.org type, and Google's position is that structured data it does not use causes no problems for Search. Your markup is not penalized. It just produces nothing visible in Google.

So why build the block? Three reasons hold up, and one popular one does not.

I would rather say that plainly than sell you a benefit I cannot measure. Our post on why FAQ schema still earns its place has the longer version of the argument.

The demand is real even without the rich result. That FAQ schema post pulled 190 impressions and 5 clicks at an average position of 19.8, making it the second most clicked page on this site after the homepage. The query faq pages seo 2026 shows up in our Search Console data at 18 impressions and position 42, meaning we barely rank for it and it still finds us.

Three ways to add FAQ to a Shopify blog post

Route 1: The details tag, in the editor today

No theme code, no app, and it works in the blog editor right now. The details and summary elements are native HTML. Every current browser collapses and expands them with zero JavaScript, and screen readers treat them as expandable regions.

Open the post, click Edit code in the editor toolbar, and paste this at the end of your content.

<div class="sn-faq">
  <h2 id="post-faq">Frequently asked questions</h2>

  <details>
    <summary>How long does shipping take?</summary>
    <p>Orders ship within two business days. Delivery is
    three to five business days inside the US.</p>
  </details>

  <details>
    <summary>Can I return an opened item?</summary>
    <p>Yes, within 30 days, as long as the item is unused
    and you still have the original packaging.</p>
  </details>
</div>

Save, then check the live post rather than the editor, since sanitization happens on save and the preview is not the storefront. If the markup came back changed, simplify it rather than paste it back in a fight you will lose.

Unstyled, this renders as a small triangle next to bold text. Functional, plain. To make it look intentional, add the CSS once to your theme stylesheet instead of pasting a style block into every article. Thirty posts times one style block is thirty copies eating your 64 KB budget.

.sn-faq details {
  border-bottom: 1px solid #E8E8E8;
  padding: 20px 0;
}
.sn-faq summary {
  cursor: pointer;
  font-weight: 600;
  list-style: none;
}
.sn-faq summary::-webkit-details-marker { display: none; }
.sn-faq summary::after {
  content: "+";
  float: right;
  color: #801D5C;
  transition: transform 0.2s ease;
}
.sn-faq details[open] summary::after { transform: rotate(45deg); }

Best for: stores publishing under two posts a month, or anyone who wants an FAQ block live in the next ten minutes.

Route 2: A theme block for Horizon-era themes

If you are on Horizon or another recent Online Store 2.0 theme, you can build the FAQ as a proper theme block instead of pasting HTML into each post. Horizon's source is built around theme blocks, so a new block file becomes available in the block picker once you save it.

The shape of the work: create a new file in the theme's blocks/ directory, give it a schema so its settings appear in the editor, and write the Liquid and CSS it needs. Do not edit Horizon's core block files directly. Horizon updates often and your changes get overwritten when it does.

The honest catch: because the Blog post section does not currently accept arbitrary blocks alongside the article body, your FAQ block sits above or below the content section rather than inside it. For most posts that is fine, since the FAQ belongs at the end anyway. If you want it mid-article, Route 1 is still your only option.

Best for: stores on a current theme, publishing weekly, comfortable adding one file and not touching the rest.

Route 3: Template-level FAQ for stores publishing on a schedule

Worth building once you publish two or more posts a week. Instead of writing the FAQ into the post body, you store it as an article metafield and render it from the template.

Set it up once under Settings, then Custom data, then Blog posts, and add a metafield definition. The Shopify article object exposes those metafields in Liquid, so your template can loop over them and render the block.

The reason this route earns its setup cost has nothing to do with convenience. The visible FAQ and the JSON-LD render from the same field, so they cannot drift apart. Every mismatch problem in the next section disappears at the template level.

Best for: two or more posts a week, or anyone who has already caught their schema saying something different from their page.

How to add a table of contents with jump links

A Shopify table of contents is simpler than the FAQ block. It is a list of links pointing at ids you are about to add. No app, no JavaScript, three steps.

Step 1: Give every H2 an id

In the HTML view, add an id attribute to each section heading. Keep them short, lowercase, and hyphenated, and make sure no two match. The id is what the link points at, so id="measuring" pairs with href="#measuring".

Step 2: Paste the table of contents

Put this after your opening paragraph rather than before it. Readers want a sentence of context before they get a menu.

<nav class="sn-toc" aria-label="Table of contents">
  <p><strong>In this post</strong></p>
  <ul>
    <li><a href="#why-fit-matters">Why fit matters more than size</a></li>
    <li><a href="#measuring">How to measure at home</a></li>
    <li><a href="#between-sizes">What to do if you are between sizes</a></li>
    <li><a href="#post-faq">Frequently asked questions</a></li>
  </ul>
</nav>

<h2 id="why-fit-matters">Why fit matters more than size</h2>
<p>Your section copy goes here.</p>

<h2 id="measuring">How to measure at home</h2>
<p>Your section copy goes here.</p>

Swap the labels and ids for your own sections. If you write to a consistent structure this becomes mechanical, which is one reason we use the same blog post template for every article: the ids and the table of contents entries come from one outline, so they cannot fall out of step.

Step 3: Fix the sticky header offset

Almost nobody warns you about this one. If your theme has a sticky header, a jump link scrolls the heading to the very top of the viewport, where the sticky bar covers it. The reader lands a line below where they expected and assumes the link is broken.

One CSS property fixes it. Add scroll-margin-top to your headings in the theme stylesheet, roughly your header height plus breathing room. CSS-Tricks has the full explanation of why this beats the old negative-margin tricks.

html { scroll-behavior: smooth; }

.article h2[id],
.article h3[id] { scroll-margin-top: 100px; }

Matching FAQ schema to what the reader sees

If you add FAQ schema on top of the visible block, one rule matters more than every technical detail: the schema must say what the page says, word for word.

Google's structured data guidelines have always required markup to reflect visible content, and that requirement did not leave with the rich result. Bing and the retrieval crawlers apply similar logic. A schema block full of questions that do not appear on the page is worse than no schema at all. Two rules follow.

Use JSON-LD only. Put a single FAQPage block in the page head or template, and do not also add microdata attributes to your visible details elements. Doing both describes the same content twice and reports as a duplicate structured data warning. JSON-LD is the easier one to maintain.

Generate both from one source where you can. This is the argument for Route 3. When the visible block and the JSON-LD come from the same metafield, they cannot disagree. When you hand-write both, they eventually will, usually because you edited an answer on the page and forgot the schema. The same parity rule applies to product schema on Shopify.

What goes wrong, and what to check first

Most of these have nothing to do with your HTML being wrong. They are environment problems, which is why they are hard to debug from inside the editor.

That last row deserves a note. A table of contents earns its place on a long, sectioned, reference-style post. It does not help a 900-word update. We covered how long a Shopify blog post should actually be if you want the ranges by post type.

One more use for the questions once you have them. They are the same ones landing in your inbox, which makes them the answers a support bot should already know, so turning your FAQ into a chatbot is the natural next step for the same content.

Wrapping up

Two things to take away. First, add FAQ to your Shopify blog posts for the reader and for the question wording, not for a search feature that stopped existing in May 2026. If a question did not come from a real customer, it does not belong in the block, and no amount of schema changes that.

Second, pick the route that matches how often you publish. If you post twice a month, Route 1 is not a compromise, it is the right answer. Pasting a details block into the HTML view takes five minutes and costs nothing. Spending an afternoon on a theme block to save three minutes a month is work you do not need to do yet. Move up when the per-post effort starts to hurt, not before.

The part I will not pretend is easy is writing the questions. The implementation here is an hour at most. Deciding which six questions genuinely deserve the page, phrased the way a customer types them rather than the way you describe your own policy, is what determines whether any of this does anything. Pull them from your support inbox, chat transcripts, and product page questions. If you cannot find six, use four. A short FAQ block of real questions beats a long one padded with questions nobody asked.

Start with the table of contents on your longest existing post and the details block on your next new one. Twenty minutes of work, and enough to see whether readers use them before you build anything bigger.

Or email contact@studioniza.com if you have a specific question about your store. I read every one.