Winning SEO with rich text in Contentful

Organic search: a human figure looking at organic materials through binoculars.
January 13, 2020


Organic search helps your organization grow, especially when you're a little cash strapped. If you can’t compete against those in the market paying for ads, you need to appear first underneath them in search results.

As the CTO at Upsolve, a small non-profit, I do everything I can to make the work of our writers go farther. This guide is a starting point for maximizing the effectiveness of content to win that number-one spot. It covers one part of our content-creation process. I hope it'll help other developers better support the work of their writers.

There’s a lot to consider when creating content that can thrive in Google’s search rankings. We’ve augmented written content using the rich text field to support semantic HTML, internal page linking and a robust JSON+LD creation. These are the details that help your page’s copy get parsed, your page sub-headers noticed in searches and your content structured as rich text snippets. Rich text allows us to accomplish all of these goals without giving writers more work.

This is what rich text snippets look like in Google:

Screenshot 2020-01-13 at 14.01.07

What is rich text?

Rich text is a way of describing content as a list of nodes. In an interface, however, rich text feels like any other document app to writers. This gives programmers predictable structures to analyze and transform without adding overhead to writers. For those unfamiliar with what rich text looks like in practice, here is an example of the node list we get from our “rich text” content field we use for article content:

Screenshot 2020-01-13 at 14.20.57

From this, you can see how it’s easy to transform this content node list into React components and pass it to other parts of your template layouts.

Processing rich text for clean <section />s

Screenshot 2020-01-13 at 14.21.53

Example of Sectioning based on form headers

In SEO, we’re often playing a guessing game of what the algorithm prefers. I’m pretty sure that the better content is organized on a page with semantic HTML 5 tags, the easier it is for a web crawler’s machine to understand that content. One way we’ve tried to do this is by encompassing blocks of content in each of our <article />s within <section />s.

We do this automatically without model bloat and information duplication in Contentful by treating headers as our section dividers. Before rendering our array of rich text nodes to HTML, we split that list on each header two, creating an array of rich text node arrays.

From there we render out each set of elements within their own `<section>`. With the leading headers at the top of each section and the following elements, I imagine this will help a crawler and web-parser more easily understand where a sub-grouping of content starts and ends, and the keyword header relates.

Processing rich text to generate internal page navigation

I've repeatedly seen our article sub-headers surface when testing search queries against our content. Sometimes sub-sections of some articles will be listed higher in results than articles we write specifically for a question. Writers don’t need to be concerned with creating internal linking for a page, which can be offloaded to simple functions.

Screenshot 2020-01-13 at 14.24.48

Example of sub-headers identified by Google’s crawler, highlighted in rich results

Automatically creating internal page anchors takes two steps. First, parse the initial rich text node list for all header twos like before. Take those strings and create a leading <nav /> component with the listed items included. Link to the page with a simple kebab casing function. As we generate our HTML tags and come across a heading two entity, we know to include an id that is also kebab-cased matching our inserted navigation above.

In the end you have a reliable automatic way to highlight headers to the Google Search Engine.

Processing rich text to create valuable JSON+LD

JSON+LD allows your pages and content to appear as rich text snippets in Google search results page, or SERP. These expanded expressions of your content appear first in search results below ads, and they can draw attention better than a link in results because of their unique structure and size.

JSON+LD is a json array that you save in the <head /> of your page, with each object describing a thing in the world, whether that’s a how-to guide, a business, a customer review, etc. You can expect and find the data structure for nearly anything on When we described our articles as how-to guides, Google’s crawlers used that additional information to showcase the above image before they even publicly announced using the how-to JSON+LD type.

We feel writers shouldn’t have to worry about these specifics, so we gave our writers a structured way to write parts of their content with embedded models in rich text. The most common place we use automatic json+ld creation and cleaner HTML structuring is with our how-to guides, such as “How to File Bankruptcy in New York”.

Screenshot 2020-01-13 at 14.28.52

In our setup, we’ve created specific models that match the JSON+LD and schema markup specifications that Google has for how-to guides. When our writers want to create a multi-step guide, they know to use this component that asks for all the information in a simple structured way.

Screenshot 2020-01-13 at 14.29.36

This consistent structured input allows us to do three things.

  1. It allows us to format content in semantically appropriate HTML, properly create sub-navigation and link it and have it nicely nested in other content.

  2. The structured data format allows us to transform these steps into comprehensive JSON+LD.

  3. Because the component rendering our HTML markup is also generating our JSON+LD, we can make direct navigation references between our JSON+LD and HTML code elements. For example, saying what the anchor link will be for a specific how-to step. This third part is where I’ve seen the least optimization done by competitors, and may be the reason why our rich snippets have so consistently appeared.

SEO content models are duplicative

We’ve gone through several versions of content writing to make our writers’ web pages perform better in organic search. I hope the above examples have shown how embedding SEO knowledge into your rich text models can save your writers time in producing content by cutting down on the fields they need to input. It’s time to ditch that SEO model!

Scratching the surface

Our content-creation process has enabled a handful of contributors to create content that now generates us over 1.5 million unique visitors a year. We spend $0 on ads and beat publicly traded companies for these top search-result spots.

The rich text feature has allowed Upsolve to structure content in ways that web crawlers love without adding burden to the content creation process. Content creation for our organization is a product and core competency, so engineering has a responsibility to empower their efforts to be world class.

As you embark on your journey to use the rich text content type, I encourage you to go beyond the formatting tips that I’ve talked about and think about how programmatic control of your content can inform the entire experience a user has and modify it over the years to stay relevant. Featured snippets like FAQs, image carousels and star ratings can not only improve the user experience, but can increase your CTR (click-through rates) and conversions.

Start building

Use your favorite tech stack, language, and framework of your choice.

Frequently asked questions (FAQs)

What is the difference between plain text and rich text?

Plain text has no formatting, rich text does allow formatting.

What is the difference between rich text and HTML?

Both are used to format text, however, rich text is used to format documents and HTML to markup the structure of web pages as well as information that is used in a search engine results page (SERP), such as title tag and meta description.

About the author
Photograph of author, Mark Hansen
Community Contributor

Don't miss the latest

Get updates in your inbox
Discover how to build better digital experiences with Contentful.
add-circle arrow-right remove style-two-pin-marker subtract-circle remove