How to Create Accessible Articles in Confluence Cloud

[#1]

Learn how to create accessible articles in Confluence that more people can read, navigate, and use

Who this is for

Anyone who creates or maintains Confluence documents or articles in Confluence.

What you'll learn

Practical steps for structuring, writing, formatting, and reviewing Confluence articles so they are easier to access with assistive technology and easier for all readers to understand.

Why this is important

Accessible documentation helps people with permanent, temporary, and situational disabilities. It also helps readers who are multitasking, using mobile devices, reading in a second language, working in bright or noisy environments, or relying on keyboard navigation.

A note about WCAG

Confluence targets conformance with the Web Content Accessibility Guidelines (WCAG) 2.2 at Level AA, as well as the Authoring Tool Accessibility Guidelines (ATAG). This means Atlassian designs and evaluates Confluence to support the applicable WCAG 2.2 AA success criteria, while recognizing that accessibility can also depend on the content authors create, configurations, integrations, and the user's assistive technologies.

To learn more, visit Atlassian Accessibility. To download the latest Voluntary Product Accessibility Template (VPAT) documents, visit Atlassian Accessibility conformance reports.

What accessible articles look like

An accessible article is structured clearly, written plainly, and usable without relying on sight, color perception, or a mouse. These practices help people who use assistive technology and also make articles easier for everyone to scan, search, and follow.

• Article titles and headings describe the task or topic clearly
• Headings follow a logical order
• Links clearly describe where they go
• Screenshots and diagrams include meaningful alternative text
• Tables are used only for real data and include header rows
• Color is never the only way information is conveyed
• Videos and visual media include captions, a summary, or a transcript
• Content is readable, concise, and easy to scan

Structure articles for easy navigation

Use headings in order

In Confluence, the page title acts as the top heading. In the article body, use headings to organize the content into meaningful sections that readers can navigate with assistive technology or by scanning the page.

• Use headings to divide the page into meaningful sections
• Do not skip levels
• Keep heading text descriptive and specific
• Avoid using bold text as a visual substitute for a heading

Good article structure: Summary → Before you begin → Steps to complete the task → Troubleshooting → Related resources

How to do this in Confluence

1. Place your cursor on the line of text you want to make a heading.
2. Open the text style dropdown in the top-left of the toolbar. It says Normal text by default.
3. Select the heading level you need, such as Heading 2 or Heading 3. The page title is automatically Heading 1, so start body headings at Heading 2.
4. You can also type ## at the start of a line to create a Heading 2, ### for Heading 3, and so on.

Keep content easy to scan

People often visit articles when they are trying to solve a problem quickly. Break content into short sections with concise paragraphs, lists, and clear labels.

• Prefer short paragraphs over dense blocks of text
• Use numbered lists for steps
• Use bullets for related points
• Put the most important information first

How to do this in Confluence

• To create a numbered list, type 1. with a space at the start of a line, and Confluence will auto-format it. You can also click the numbered list icon in the toolbar.
• To create a bullet list, type * or - at the start of a line, or click the bullet list icon in the toolbar.
• To break up long paragraphs, press Enter to create a new paragraph. Aim for 2–4 sentences per paragraph.

Write articles that are clear and actionable

Use plain, direct language

Write for clarity. Simple language helps a wider range of readers, including people using assistive technology, people reading quickly, and people reading in a second language.

• Use familiar words
• Prefer active voice
• Keep sentences reasonably short
• Explain acronyms the first time you use them

Make instructions explicit

Avoid direction that depends only on vision or layout.

Avoid	Use instead
Click the button on the right	Select Create
See the red message below	Review the error message under Email address

Write meaningful link text

Link text should tell readers what they will open. This is especially important for screen reader users who may navigate by links alone.

Less accessible	More accessible
Click here	Read the access settings guide
Learn more	View Atlassian guidance for public knowledge base access

For public documentation, avoid pasting long raw URLs into the body when descriptive linked text will do the job more clearly.

How to do this in Confluence

1. Select the text you want to turn into a link.
2. Press Ctrl+K on Windows or Cmd+K on Mac, or click the link icon in the toolbar.
3. Paste or search for the URL in the link field.
4. The selected text becomes the link text. Edit the display text if needed.
5. Press Enter or click Insert to apply.
6. To edit an existing link, click the link, then click the pencil icon in the floating toolbar. You can change both the URL and the display text.

Make screenshots, video, and visual content accessible

Add alt text for meaningful images

If an image adds information, its alt text should communicate the same purpose or takeaway.

• Describe what matters, not every visual detail
• Keep alt text concise and specific
• Avoid starting with "Image of" or "Picture of"

Example: Instead of chart, write Bar chart showing article views increasing each month from January to April.

How to add alt text in Confluence

1. Insert an image by dragging it onto the page, pasting it from your clipboard, or typing /image and selecting Image.
2. Click the image once it is on the page. A floating toolbar appears above or below the image.
3. Click the Alt text button in the floating toolbar. It may appear as "Alt text" or as an icon with "Alt."
4. If you do not see that button, keep the image selected and open the right-side properties panel. Look for the Alt text field.
5. Type a concise, meaningful description of what the image communicates.
6. Press Enter or click away to save.
7. To verify it, click the image again and confirm the alt text appears in the properties panel.

Skip decorative images

If an image is purely decorative and adds no meaning, it should not create noise for assistive technology users.

How to do this in Confluence

For purely decorative images, such as dividers, background shapes, or brand flourishes, leave the alt text field empty. Click the image, open the alt text field, clear any text, and save. Empty alt text tells screen readers to skip the image.

Provide text alternatives for video

If you embed a walkthrough or demo, include a short written summary and, where possible, a transcript or captions. Readers should still be able to understand the content without watching the video.

How to do this in Confluence

• When embedding a video, paste the video URL into the page, type /loom, or use the Widget macro if appropriate.
• Add a written summary directly below the embedded video so readers can understand the key points without watching.
• For Loom videos, use Loom's generated captions and transcript. Copy the transcript into an Expand macro below the video titled Video transcript.
• For YouTube videos, enable captions in YouTube Studio before embedding, and add a brief written summary on the Confluence page.

Tables, status, and color

Use tables only for data

Tables should present structured information, not create visual layout. Keep them simple and include a header row.

• Use a header row for column names
• Keep tables as simple as possible
• Avoid merged cells unless truly necessary
• Do not place paragraphs of procedural content inside tables

How to do this in Confluence

1. Type /table and select Table, or click the + Insert button in the toolbar and choose Table.
2. Confluence usually creates the first row as a header row with a shaded background.
3. If the header row is not set, click inside the top row, open the table options in the floating toolbar, and toggle Header row on.
4. To add or remove rows or columns, click inside a cell and use the floating table toolbar buttons.
5. To set a header column, click inside the first column, open the table options, and toggle Header column on.

Do not rely on color alone

Color can support meaning, but it should not be the only signal. A person may not perceive color differences, and assistive technologies may not announce them.

• Pair status colors with text labels
• Use clear wording such as Blocked, In progress, or Complete
• Check that text has sufficient contrast against the background

Common Web Content Accessibility Guidelines (WCAG) contrast targets include 4.5:1 for normal text and 3:1 for large text and many user interface elements.

How to do this in Confluence

• When using a status lozenge, type /status, choose a color, and always enter a text label such as Complete, In progress, or Blocked.
• When highlighting text with a background color, also add visible wording such as (Required) or (Warning) so the meaning is not conveyed by color alone.
• If you manually change text or background colors, check that the contrast ratio meets 4.5:1 for normal text. You can use the WebAIM Contrast Checker.

Forms, macros, and interactive content

Use labels for form fields

If your Confluence page includes embedded forms, Jira Service Management request forms, or links to service experiences, each field should have a clear visible label that is programmatically associated with the field. This helps screen reader users understand what information belongs in each input.

Watch for: A text box that appears visually labeled but is not announced correctly by a screen reader. This can happen when the field and label are not properly connected.

How to check this from Confluence

Native Confluence pages usually do not contain form fields directly. If your article links to or embeds Jira Service Management request forms, check labels in Jira Service Management: go to the JSM project, select Project settings, choose Request types, edit the form, click each field, and confirm that a clear label is set in the field properties panel.

Use macros carefully

Most Confluence formatting features can support accessible content when used thoughtfully, but some patterns need extra care.

Feature	Use it for	Accessibility guidance
Info, note, or warning panels	Important callouts	Helpful when used sparingly and paired with clear text
Expand sections	Optional supporting detail	Use only for non-essential content and test that hidden content remains understandable when expanded
Status indicators	Compact state labels	Include text that states the meaning, not color alone
Table of contents	Long pages with many sections	Useful for navigation when the page has a strong heading structure

How to insert these macros accessibly

• Info, note, or warning panels: Type /info, /note, or /warning, then add explanatory text inside the panel. Do not rely on the icon or color alone.
• Expand sections: Type /expand, give the expand a clear title, and place only supplementary, non-essential content inside.
• Status indicators: Type /status, choose a color, and type a clear status label such as Complete, In Progress, or Blocked.
• Table of contents: Type /toc or /table of contents. The macro automatically creates links from your page headings, so it works best when headings are ordered logically.

Build an accessible article: example workflow

1. Choose a clear, task-focused title that describes what the article helps readers do.
2. Add a short summary near the top so readers know whether the article applies to them.
3. Organize the article with headings such as Before you begin, Steps, Troubleshooting, and Related resources.
4. Use numbered lists for procedures and bullet lists for related information.
5. Add meaningful alt text to screenshots, diagrams, and charts that provide information.
6. Replace vague links such as "click here" or "learn more" with descriptive link text.
7. Use tables only for structured data, and include a header row.
8. Do not use color as the only way to show status, errors, warnings, or required actions.
9. Provide captions, transcripts, or written summaries for embedded videos and demos.
10. Review the article with keyboard-only navigation and, where possible, a screen reader before publishing.

Before you publish

• The page language is identified correctly (this is a site-level setting — site admins go to Settings → Languages & time zones)
• Headings are in a logical order
• Paragraphs are short and readable
• Link text is descriptive
• Images have appropriate alt text
• Videos include a summary, captions, or transcript
• Tables use a header row and only present data
• Color is not the only way meaning is communicated
• Form fields have clear labels
• Expand sections contain only optional detail
• The page can be understood without relying on layout or visuals alone

How to test before publishing

• Keyboard-only check: After publishing, press Tab repeatedly to move through links, buttons, the table of contents, and expand sections. Confirm that you can see where focus is, activate links and buttons with Enter, and open or close expands with Enter or Space.
• Basic screen reader check: On Mac, press Cmd+F5 to turn on VoiceOver. On Windows, press Ctrl+Win+Enter to turn on Narrator, or use NonVisual Desktop Access (NVDA). Navigate the page and listen for clear heading announcements, meaningful link text, and image alt text.

[Caity Belta]

Thank you, @Andy LaHart !! Bit of a meta-compliment on your posting style, but I really love how you clearly stated the who, what, and why up front! The content itself is also very informative :)

[Roger]

A useful feature for Confluence would be: send a signal to someone you assign - per page.
So that they can check if the page is still up to date.

[Mia Tamm _Simpleasyty_]

Really useful guide, @Andy LaHart. I like that you’ve treated accessibility as part of writing and structuring the content, not something to check at the very end.

The examples around headings, link text and images are especially practical — small changes, but they can make a big difference to how usable a Confluence page actually is.

Great resource to keep bookmarked.