Formatting Content – Best Practices

The Confluence editor gives you a lot of flexibility to format and lay out your content. The tips on this page will help you create readable, structured and engaging content for your audience in Viewport.

Structure content with Headings

Format your text to increase readability and navigability of content. Make use of headings to structure articles and help users navigate the content.

If you enable the table of content (TOC) option for articles in the Theme Editor, Scroll Viewport will automatically generate a structured list of links pointing to the first three levels of headings found on your article:

• If you start your Confluence pages with H1s: The TOC will show H1, H2 and H3.

• If you start your Confluence pages with H2s: The TOC will show H2, H3 and H4.

In the Help Center theme, your article titles will display the HTML Heading 1 style. To ensure a hierarchical structure in the HTML output, any headings that you have formatted as H1s in Confluence will automatically be transformed into H2s by Scroll Viewport.

Be careful with Layouts

The Confluence editor lets you structure the content of a page into columns and give each part of the page a different column configuration. This option is called Layouts in the editor toolbar.

Layout are a powerful tool to control the visual impact of the content in your Viewport articles but you should be deliberate and careful when using them, as the available content width in Viewport is much narrower than in Confluence.

Don’t use layouts with multiple columns for lengthy content or tables as users will have to scroll more to read all of the content. Generally speaking, 50-75 characters per line can be easier to read.

Hide less relevant content in Expands

Confluence’s Expand macro lets you hide content away in a section that users can expand and collapse as needed. This is especially helpful in the following scenarios:

• You want to include content in your article that will only be relevant for a (smaller) part of your audience (e.g. advanced technical details, examples or background information).

• You want to differentiate parts of the content based on the needs, permissions and requirements of your audience. Example: distinguish instructions between operating systems.

We recommend to always carefully consider if the content should exist in the first place and yes, if it really should be hidden from view. Don’t hide important content in Expand macros as users will have a hard time finding what they’re looking for if it’s collapsed, especially if they are doing an in-page search (Ctrl+F.).

If your consistently differentiating content based on your audience’s profiel, we recommend to check out our documentation on How to Show Different Content Depending on the Audience .

Distinguish code from content with Code formatting

When inserting code examples in your articles, use Confluence’s Code Snippet macro and select the respective language. Viewport will show the syntax highlights for most common lanuages.

For any other in-line code references, you can use the editor’s Code formatting which looks as follows:

example code

This will help your readers easily differentiate between normal text and code.

Highlight information with Panel macros

Highlight important information in your content with the help of Panels. Confluence provides some pre-determined panels that you can use for different types of information, for example warning panels for critical information.

Viewport will also display any custom panels you create. Try to find a consistent language, so users can learn what the different colors and emojis mean and what information they might contain.

Dos and Don'ts

Let’s summarize what you should and shouldn’t be doing in your help center articles.