How to create a content model for a documentation page

Sample design

For the purpose of this article we're going to use this mockup – it contains a few elements typical to a documentation page.

The content model: what's dynamic, what's static

Static Fields
Dynamic Zone

Page Title

Every page that we create will have a title at the top. We will model this using a Text field.

1 of 5
< PreviousNext >

Text Block

This will consist of a Text field to allow the authors to add their text content.

2 of 5
< PreviousNext >

Code Snippet Block

This will consist of Text field for the code snippet text.

3 of 5
< PreviousNext >

Highlighted Text Block

Here we will use a Text field for the title and another Text field for the main text.

4 of 5
< PreviousNext >

Image Block

This will consist of an Image field to allow the content author to upload and select the image.

5 of 5
< PreviousNext >

The content model

In the static section of the page we will need the following elements:

  • Page title

In the Dynamic Zone of the page, there are 4 major content blocks:

  1. Text block
  2. Code snippet block
  3. Highlighted text block
  4. Image block

These 4 blocks will be setup in the dynamic section so that they can be freely mixed and matched to build your documentation pages.

See the introduction to content modeling for more context on dynamic and static sections.

Why is it like that

Selected approach: content blocks, everything dynamic. Given that this is a knowledge base and you will be creating lots of articles, we will compose our pages with reusable blocks. This way, the order of the content blocks can vary from page to page, and some of these sections can appear as many times as needed for each article.

Alternative approach: a single Rich Text field. Many content management systems provide a Rich Text field that allows you to add all your text and images in a single field. For some simple documentation designs, this might be enough!

Possible consequences of the single Rich Text approach. If you choose to take this approach, you'll be at the mercy of the elements provided in the Rich Text field. For example, you would have no way to add videos to your page if this isn't an option in the Rich Text field.

The content model: the fields

Choosing the fields for each section is rather straightforward:

Static Section

  • Text field for the page title

Dynamic Section

  • Text block consisting of a Text field
  • Code snippet block consisting of a Text field
  • Highlighted text block consisting of two Text fields
  • Image block consisting of an Image field

How to set it up in Prismic

  • Set up a new custom type
  • Add the fields for the static zone
  • For each of the 4 content blocks, create a separate slice
  • Add the field(s) for each slice as defined above

If you want to try this model in Prismic, copy this JSON instead of setting up the model manually:


What editors will see

When an editor creates a document based on the documentation page custom type created above, they can add any of these slices and fill the placeholders with content.

How to model content for your project Sarah will be glad to help you come up with a solid content model for your project. (It’s free.) Schedule a call