Rich text formatting guide for Jira Cloud

This page explains how to format text in Jira Cloud using Power Scripts synax. It covers basic formatting, content structure elements, tables, media embeds, detailing field compatibility and known limitations.

Atlassian Document Format (ADF) is the underlying system that powers rich text in Jira Cloud.

Formatting behavior varies between Jira DC and Jira Cloud. Jira DC typically uses Wiki Markup format. Line breaks (\n) are consistently preserved across both Jira DC and Jira Cloud.

While ADF itself is complex and requires detailed technical knowledge, Power Scripts offers a simplified syntax to help you format text in various Jira fields efficiently.

This simplified syntax:

Reduces the learning curve
Minimizes formatting errors
Maintains consistency across documentation
Converts automatically to valid ADF format

Contents: Fields compatibility Basic text formatting Content structure elements Content emphasis elements Media and attachments Building tables Format limitations

Fields compatibility

Some fields do not support rich text formatting due to their specific design purposes and technical limitations. Understanding field compatibility is crucial for effective content management.

Compatible fields:

Can store ADF content in the database
Include the necessary frontend components to display rich text
Can process and validate ADF content

The following table provides detailed information about Jira field compatibility:

Field type	Compatibility	Description

Field type	Compatibility	Description
Description		Core Jira fields that are built to process and display formatted content
Environment		Built-in Jira field designed to store detailed environment information with rich text support
Comments		Native Jira elements that support rich text for better communication
Worklog entries		Built with ADF support to allow formatted documentation of work
Built-in text fields (multi-line) *		Native Jira field designed to handle rich text content and store it as ADF
Custom fields: text field (multi-line) **		Custom fields of this type are configured to support ADF content
Text field (single line)		Designed for brief, plain text input only (like titles or short references)
Text field (read-only)		Created solely for displaying plain text without editing capabilities

A standard multi-line text field that comes with Jira

** A custom field that you create and configure in Jira

Basic text formatting

Jira supports a range of text formatting options to help you create clear, well-structured content. The tables below show the available formatting syntax, how it appears when rendered, and common use cases for each style. All formatting can be combined to create rich text content that effectively communicates your information.

Basic text styles

Style	Syntax	Result	Suggested use

Style	Syntax	Result	Suggested use
Bold	`text`	text	Use for emphasis
Italic	`//text//`	text	Use for subtle emphasis
Strikethrough	`~~text~~`	text	Use for outdated content
Underline	`__text__`	<u>text</u>	Alternative emphasis; use sparingly

Text position

Format	Syntax	Result	Suggested use

Format	Syntax	Result	Suggested use
Superscript	`^^text^^`	x^2^	Mathematical expressions
Subscript	`--subscript--`	H₂O	Chemical formulas

Text enhancement

Format	Syntax	Result	Notes

Format	Syntax	Result	Notes
Color text	`{{color:#FF0000}} red text{{/color}}`	red text	Use hex colors only There should be no spaces before `:`
Links	`[[https://example.com\|\|Visit example]]`	Visit example	Double pipe separates URL and text

Other elements

Formatting	Syntax	Notes	Example

Formatting	Syntax	Notes	Example
Break in paragraph	{{break}}	No ending tag. Breaks in paragraphs.	[line break]
Unicode emoji	`{{emoji}}char\|\|text\|\|emoji_id{{/emoji}}`	Includes three parts separated by double pipe Unicode emoji Emoji shortcode Emoji ID	`{{emoji}}🙂\|\|:slight_smile:\|\|1f642{{/emoji}}`
Mention	`{{mention}}@Username\|\|userID{{/mention}}`	Must contain `@` right after `{{mention}}`	@John Smith
Inline code	``code here``	Use two backticks with no space after opening or before closing. Inline code is for short snippets within a line of text, commands, or technical terms; do not cofuse with code blocks (used for multiple lines of code)	Commands example: Run ``npm install`` to install dependencies Use the ``--force`` flag if needed Technical reference example: The ``userId`` parameter must be an integer Access the API at ``api/v1/users``

Example

This code demonstrates how to build a multi-line description string that showcases various text formatting options in Jira.

description += "Examples: **bold** , //italics// or ~~strike through~~ and __underline__.\n";
description += "Links are given like this: [[https://google.com||Google text that appear]].\n";
description += "This is some {{color:#2266AA}} colored text{{/color}} followed by normal text.\n";
description += "Emojis: {{emoji}}🙂||:slight_smile:||1f642{{/emoji}} {{emoji}}😄||:smile:||1f604{{/emoji}} or a custom one {{emoji}}🎺||:trumpet:||1f3ba{{/emoji}}\n";
description += "A mention: {{mention}}@John Smith||6093b81a539c14006ad3c137{{/mention}}\n";
description += "A--Subscript-- and A^^Superscript^^\n";

Let’s analyze each line:

Line #1	Shows four basic text styles in one line `\n` adds a new line
Line #2	Demonstrates link syntax with URL and display text URL and display text are separated by `\|\|`
Line #3	Shows how to add colored text (blue shade) Demonstrates mixing colored and normal text
Line #4	Shows three different emoji examples Each emoji has three components: Unicode emoji (🙂, 😄, 🎺) Shortcode (:slight_smile:, :smile:, :trumpet:) Emoji ID (1f642, 1f604, 1f3ba)
Line #5	Demonstrates how to mention a user Includes username and user ID
Line #6	Shows both subscript and superscript formatting

Escaping special characters in Jira text

When you need to display formatting characters as plain text (like showing -- or ** literally) rather than using them for formatting, you'll need to use escape characters. The method differs depending on whether you're typing directly in Jira or writing code:

Direct text input (in Jira UI)

Single backslash (\) is used to escape special characters
When typed directly in Jira, \-\- will display as -
Instead of creating subscript text, it will show literal hyphens
Result: -- appears as plain text instead of creating subscript formatting

Example

Programming context (in code)

Double backslash (\\) is required in code strings. This is because:
- The first \ escapes the second \.
- The resulting single \ then escapes the special character.
Same end result as above, but requires double backslashes in code.

Example

Examples comparison

Context	Syntax	Result

Context	Syntax	Result
Direct in Jira	`\-\-text\-\-`	`-text-`
In code	`"\\-\\-text\\-\\-"`	`-text-`

Content structure elements

These core formatting elements are used to organize and structure your Jira content hierarchically.

Element	Syntax	Notes and examples

Element	Syntax	Notes and examples
Headers		Headers help organize content into hierarchical sections. Jira supports six levels of headers. Each header must be placed on a separate line. End headers and separators with `\n` This example creates a level 2 heading and adds a dividing line under it:
Lists		Jira supports two types of lists to help organize and structure your content: bullet lists for unordered collections and ordered lists for sequential items. This example creates a paragraph text followed by numbered steps 1 and 2:
Panels		Panels are HTML-style containers that highlight content with distinct visual styles. You can include rich text in panels by marking the text with `<!` and `!>`delimiters on separate lines. This example creates an info panel and uses bold text formatting:
Tables		HTML-style tables are useful for organizing data in rows and columns.

Examples

This example creates a level 1 heading, adds a dividing line, and adds text under the dividing line.

Content emphasis elements

These formatting elements are used to highlight, quote, or distinguish specific content.

Element	Syntax	Notes

Element

Syntax

Notes

Quotes

Quotes in Jira are used to visually distinguish referenced or cited content from regular text.

The example creates a paragraph followed by a two-lines quote:

Code

Code is typically used in technical content and code snippets. Jira supports two types of code formatting:

Inline code
Code blocks; can have language reference

This example creates level 4 heading and adds a Java code block under it:

Media and attachments

These are elements for including and managing non-text content in your Jira items. This includes attached documents, images, videos, and other media content.

Element	Syntax	Notes

Element

Syntax

Notes

Single media

You can embed media files in two ways: single media element or multiple media elements.

Each media element requires these parameters, separated by #:

uuid: Unique identifier of the attachment
type: File type (for example, 'file', 'image')
width, height: Display dimensions
collection, occurrence: Internal Atlassian identifiers

Multiple media

Building tables

Jira offers three types of tables to help you organize and present information effectively: basic tables for simple data presentation, styled tables for customized formatting, and dynamic tables for automated content generation.

Every table has these main elements:

<table></table>: Container for the entire table
<tr></tr>: Table row container
<th></th>: Table header cell
<td></td>: Table data cell

Basic Tables

Basic tables use the following syntax:

Example

This example demonstrates code for a simple table with a header row, 3 data rows and 3 columns. The last row demonstrates column spanning.

This example code renders the following table:

This screenshot illustrates the result of the code example.

Example table

Decorated (styled) tables

You can use table layout and table cell properties to add styling to a table.

Style element	Property	Description	Examples

Style element	Property	Description	Examples
Table layout	`default`	Suited for most cases; fits content within normal margins	In this example, you define a table with numbered rows which uses the default layout:
	`full-width`	Uses the entire page width; good for large datasets
	`wide`	Extends beyond normal margins; useful for complex tables
Table cell	`colspan`	Merges cells horizontally across columns Takes a numeric value
	`rowspan`	Merges cells vertically across rows Takes a numeric value
	`background`	Sets the cell's background color Uses hex color codes

You can use multiple properties in the same cell. In your code, space-separate the properties as shown in this example:

Rich content in cells

To add complex formatting with a table cell, follow these guidelines:

Use <! and !> markers on separate lines
You can include any supported Jira formatting
Suitable for embedding media, panels, or code blocks

Examples

This example demonstrates the syntax for embedding a note panel in a cell:

This more complex example demonstrates the following rich text formatting:

Basic table structure
Column spanning
Rich text formatting
Embedded note panels
Proper escape marker usage

Dynamic tables

Tables can be generated dynamically from data sources, such as CSV files or databases. Use dynamic tables when data needs to be automatically populated or updated.

This example demonstrates how to create a table automatically in response to user comments:

Here's what it does:

Monitors for new comments on a Jira issue
When a comment starts with "Country:,” the automation:
- Extracts the country name from the comment
- Searches for matching countries in a CSV file
- Creates a formatted table with the results
- Updates the issue description with the new table

While this example uses a CSV file (countries.csv) as the data source, you can adapt the code to fetch data from any source, such as a database or API.

Format limitations

Power Scripts for Jira Cloud provides partial support for ADF. Known formatting limitations:

InlineCards are not yet supported.
Nested tables (tables within tables) are not allowed.
Some formatting features that work in our system may be rejected by Atlassian.

Malformed documents

When formatting errors are detected, the system returns an error document listing the issues. You can fix the errors and reapply formatting using this SIL script: