Best way to create an FAQ with schema

I’m considering moving a WP site to Hugo, but I have a ton of pages with FAQ sections within the content of the page. These sections also generate the FAQ schema: FAQPage - Type

In WP this can be done easily. I have a Gutenberg block that provides the HTML structure and then generates the schema.

In Hugo, how would something like this be done in markdown files? I guess I could add the HTML to the markdown, but how would the FAQ schema be generated from that?

Maybe I need to use data files for each FAQ section? Seems like a maintenance headache to me with over 100 FAQ sections. Can data files support markdown content?

Ideally, I’d like to keep the FAQ content within the markdown for that page, but I can’t come up with a way to generate the schema when doing that.

Anyway, I’m not sure how best to go about this. Any advice on how to create structured content within Hugo?

No. You would need to use a Partial template to generate the relative markup and then call it from the head element of a Single Page Template or a List Page Template

You can use Page Variables as well as Front Matter Parameters in each content file or as you mention above you could use Data Files to populate the schema.

If you have a tool that generates the schema for each content file then it would probably make sense to have it as a Page Resource so that it resides within a Page Bundle and then call it from the templates.

Your question is very broad -as you may have noticed I have linked to several parts of the documentation above- and provide alternative paths you could use to achieve what you want.

Hugo is agnostic and there are no cookie cutter tools, but you most likely can generate what you need on your own with standard Hugo Templates logic.

@teamcrisis you can look at my post about Manage easily any SEO thru your different sites.

You can adapt the code for a FAQ part. Do not hesitate to ask if it is not clear.

In your case, add this in your front matter of each faq page, and create a seo_metadata_faq.html partial based on my code. Should do the trick

typeseo = ["faq"]

@divinerites thanks for this, it gives me something to go off of.

One issue I’m finding - I’m not trying to create an entire FAQ page, it’s simply a section of content within a regular article page.

For example, here is a page outline:

Heading 1


Heading 2


Question 1
Answer 1
Question 2
Answer 2

Heading 2

Under the FAQ section I need to take the Questions and Answers and loop through them to generate the schema.

The FAQ section is made up of H2 for the questions and answers are any combination of p, ol, ul, li, a, strong, img tags.

I guess what would be the most ideal situation for me is this:

  1. In the front matter, have faq: true
  2. Add the FAQ section somewhere in the markdown content
  3. Parse the markdown content, find the FAQ section and find each question and answer and loop through them to generate the schema.

Probably the best way of doing the above would be to have the questions and answers as front matter parameters in a content file.

Then call these parameters in a Partial, so that you can loop through the questions and answers to generate the faq schema and then also call them through a Shortcode to render them where needed in the body of the content file.

For example in a content file you could define questions & answers and use a shortcode like so:

question = "Lorem Ipsum?"
answer = "Lipsum"
Heading 1


Heading 2


{{< faq >}}

Heading 2

@alexandros Thanks, yes, I was considering this.

My primary concern is the need for various elements such as lists and multiple paragraphs in each answer section.

The answers are not typically a simple string of text. They are often a combination of 1-2 dozen HTML tags to make up the complete answer.

I tried looking through the docs, but is standard markdown supported in the front matter? The people writing the content are not very technical, so deviating from standard markdown is probably going to cause issues for us.

There are two things you need to consider.

Render the schema in the head and also render it at the appropriate place in the body of a page.

Looping through front matter parameters is always simpler.

However from your description perhaps it would be best for non technical writers to write what is required outside Hugo and then have the generated HTML in separate files under a Page Bundes so that these can be called as Page Resources in the templates.

Perhaps others have more ideas about how you could go about generating the faq.

Front matter parameters accept strings, booleans, integers (perhaps floats -I haven’t tried-).

A front matter parameter string can contain HTML or Markdown.

Then you can sanitize the strings as needed with functions like plainify (strip the HTML), safeHTML (render the HTML), markdownify (render the string through the Markdown processor).

See more at the Docs.

I should make clear, this issue goes beyond just FAQ. The same issue goes for other structured data types such as how-to and reviews.

Structured data is a major component of our site and the FAQ example is just a simple example of the overall issue I’m trying to solve.

Structured data is a major part of SEO nowadays, so I’m quite surprised that Hugo doesn’t have a built in way of handling this better.

I’m sure Hugo has a half-dozen ways this could be resolved, but I need to also consider ease of use for writers of the content.

Ideally, a writer should simply write the content in markdown in the order everything should appear on the page - similar to writing a standard text document.

Asking a writer to change their writing method based on the type of content being displayed on the page is a nightmare that I’m trying to avoid.

There are no plugins for Hugo as currently there is no API.

We do have Custom Output Formats that can be used in various scenarios.

@divinerites above offered a working example for a simple Schema Setup

But for the complex situation you describe, structured data that is written as complex HTML in the middle of a page’s body and then somehow loop through it to generate the Schema, that is not how things work in Hugo.

The .Content variable that holds the body of a content file is a single variable.

There have been workarounds about splitting .Content in this forum.

Like this one or this one

However looping through the split Content sections to populate a faq or other schema?
It can probably be done, haven’t really tried, but it probably won’t be clean or easy to achieve.

Ok, thanks for the help with this. That’s the general conclusion I’m coming to as well.

Is it possible to nest shortcodes within shortcodes?

I’m wondering if something like this is possible

{{< faq >}}

{{< question >}}This is a question{{< /question >}}
{{< answer >}}
### this is a markdown answer

- item 1
- item 2


{{< /answer >}}

{{< question >}}This is another question{{< /question >}}
{{< answer >}}This is a simple string answer{{< /answer >}}

{{< /faq >}}

Basically, loop through the faq shortcode and then get the inner content of each question and answer.

Nested Shortcodes are possible.

Also see: Search results for 'nested shortcodes' - HUGO

Ahh, yes, sorry I read about that yesterday but forgot about it. Ok, thanks for the help. I’ll give a few things a shot and see how the team takes it. I have a feeling we’ll have to stick with WP until something a bit more straightforward is available to writers.

If anyone is interested in what I used as a solution for creating markdown FAQ schema.

The topic is available here.