Jira Text Formatting: Guide and Examples for Jira Pages
Struggling to make Jira text readable? Explore jira format text options, editor differences, and examples. Read now to format Jira pages clearly.
Jira text can become difficult to scan when an issue description is one long block, a code example loses its spacing, or formatting symbols appear literally. That can slow reviews and leave important details hidden inside a ticket. The confusion often comes from Jira’s different editors: syntax that works in an older wiki renderer may not work in the current rich-text editor. But here's the truth: you can make Jira pages clearer once you know which editor you’re using and what it supports. This guide explains the common formatting options, shows practical examples, and helps you fix formatting that does not render as expected. You’ll also learn how to structure descriptions so teammates can find the key details quickly.
Jira text formatting: the quick guide
Jira text formatting is the use of rich-text controls, keyboard shortcuts, or supported markup to make issue descriptions, comments, and other Jira content easier to read. The available options depend on the editor and the Jira version.
In Jira Cloud’s current editor, use the formatting toolbar for headings, emphasis, lists, links, and other common styles. Some shortcuts are also available. Older Jira installations and fields using a wiki renderer may support wiki markup such as *bold* or {code}.
For example, use a heading for “Steps to reproduce,” a numbered list for the steps, and a code block for an error message. The result is easier to scan than a single paragraph containing everything.
Here’s why: markup is not universal across Jira editors. If symbols show up literally, the field may not support that syntax. Check the editor first, then choose the matching formatting method.

Choose the right Jira editor before formatting
Jira content can appear in issue descriptions, comments, and other fields. The editor available in each place affects which formatting controls and shortcuts work. If you see a toolbar with buttons for bold, lists, or links, use those controls first.
In some Jira Cloud editors, familiar keyboard shortcuts can speed up writing. Older Jira Server or Data Center installations may use a wiki renderer for certain fields. A syntax example that works in one place might display as plain characters in another.
For instance, if you enter *urgent* and it stays surrounded by asterisks, try selecting the word and using the bold button. If you maintain a customized Jira instance, check its field renderer settings or ask your Jira administrator which formatting options are enabled.
Quick editor check
- Toolbar visible: Apply formatting with the editor controls, then try supported shortcuts.
- Markup shown literally: The field may not use a wiki renderer, or the syntax may be unsupported.
- Different behavior between fields: Test formatting in the specific description or comment field you plan to use.
Common formatting syntax and examples
Wiki markup remains useful in Jira environments that support it. The examples below show common syntax, but use them only in fields where the wiki renderer is enabled. In the current rich-text editor, use toolbar controls or compatible shortcuts instead.
For example, a legacy Jira description might use *bold text* for bold, _italic text_ for italics, and -removed text- for strikethrough. Some renderers also accept +underlined text+ for underlining.
Text styles and headings
*bold text* — emphasizes a key phrase.
_italic text_ — adds emphasis without making text bold.
-strikethrough text- — marks text as removed or outdated.
h2. Steps to reproduce — creates a heading in a wiki-rendered field.
Lists, links, and code
* First item — creates a bullet item in a supported wiki renderer.
# First step — creates a numbered item in a supported wiki renderer.
[Jira help|https://example.com] — creates a labeled link in wiki markup.
{code}console.log("Ready");{code} — displays a code block in some wiki-rendered fields.
{{inline_code}} — highlights a short code term in some wiki-rendered fields.
For a bug report, you could use a heading for “Expected result,” a numbered list for reproduction steps, and a code block for the error output. That keeps each detail in a format suited to its purpose.
Structure issue descriptions for quick scanning
Good formatting supports clear writing; it cannot replace it. Start an issue with a one-sentence summary, then separate the context, steps, expected result, and actual result into short sections.
For example, a report about a checkout failure could use “Steps to reproduce” followed by three numbered actions. Under “Actual result,” add the exact error message in a code block if the editor supports one.
The best part? A consistent structure makes it easier for teammates to compare issues. If every bug report places its reproduction steps in the same section, a reviewer can find them without scanning the entire description.
A practical issue template
- Summary: State the problem and where it occurs.
- Environment: Include relevant browser, device, or application details.
- Steps to reproduce: List actions in the order someone should follow them.
- Expected result: Explain what should happen.
- Actual result: Describe what happened and include any exact error text.
Keep each section focused. A report such as “After selecting Save, the page displays a permission error” is easier to act on than “Saving does not work.”
Make formatted Jira content accessible and readable
Formatting should clarify relationships between details. Use headings in a logical order, descriptive link text, and lists only when information naturally belongs in a sequence or group. A heading such as “Browser information” tells readers more than a vague label such as “Details.”
Avoid using color or bold alone to communicate urgency. Someone may miss the distinction, and color may not appear consistently across interfaces. Write “High priority” in the text and apply the relevant Jira priority field as well.
For example, use “Open the account menu” as link text instead of “click here.” If you include a screenshot, describe the visible problem in the surrounding text so the issue remains understandable without relying on the image.
Let me explain: readable formatting helps people scan content, while clear labels help them understand it. Both matter when a ticket moves between teams or gets reviewed on a small screen.
Troubleshoot formatting that does not render
When Jira displays markup characters instead of formatted text, start by checking the editor rather than changing the syntax at random. The field may use a rich-text editor that does not interpret wiki markup, or a customized field may use different settings.
Try a simple test in the same field. Apply bold using the toolbar, save or preview the content, and check how it appears. If the toolbar works but markup does not, use the rich-text controls for that field.
Common fixes
- Symbols appear literally: Replace the markup with toolbar formatting, or confirm that the field supports a wiki renderer.
- Lists look uneven: Select the lines and apply a list style instead of mixing manual symbols with editor-generated bullets.
- Code loses spacing: Use a code-block control or supported code-block syntax. Avoid relying on repeated spaces in normal text.
- Formatting changes after pasting: Paste plain text, then apply headings, lists, and emphasis inside Jira.
- One field behaves differently: Ask an administrator to check whether its renderer or configuration differs from other fields.
You might be wondering: should you memorize every markup rule? Usually, no. Learn the controls available in the Jira fields you use most, and keep a short reference for legacy markup when your team still relies on it.
ONES.com Solution: project and knowledge work in one platform
ONES.com brings project management and knowledge management together in one platform, with ONES Project for project work and ONES Wiki for team knowledge. The products are sold separately, so teams can choose the part that fits their needs.

Value proposition
If your team spends time maintaining project workflows while keeping instructions and decisions elsewhere, ONES.com offers a way to manage both kinds of work within one platform. ONES Project is a Jira alternative, while ONES Wiki is a Confluence alternative.
Core capabilities
- Workflows are difficult to adapt: ONES Project supports custom workflows and fields, giving teams room to reflect their review and delivery steps.
- Sprint planning needs clearer tracking: Sprint management helps teams plan and follow iterative project work.
- Progress is hard to report: Built-in reporting helps teams review project status without assembling multiple reporting add-ons.
- Repeated tasks consume attention: Automation can handle recurring workflow actions and reduce manual follow-up.
- Jira-based processes are costly to rebuild: Jira-compatible workflows can help teams carry familiar project patterns into a Jira alternative.
- Too many plugins complicate maintenance: Native capabilities can reduce reliance on plugins for common project-management needs.
- Hosting requirements vary: Teams can choose Cloud, On-Premise, Private Cloud, or Air-gapped deployment.
- Self-hosted teams worry about feature gaps: ONES.com offers feature parity between cloud and self-hosted versions.
Application scenarios
A software team could use ONES Project to manage backlogs, customize issue workflows, plan sprints, and review built-in reports. If its deployment requirements call for a restricted network, it can consider an Air-gapped deployment.
A team that also needs a shared knowledge base could use ONES Wiki for internal guidance and project knowledge. Since ONES Project and ONES Wiki are sold separately, a team can select one or both according to its needs.
Common challenges with Jira text formatting
Challenge: Markup works for one teammate but not another
Why it happens: People may be using different fields, editors, or Jira configurations. A wiki-rendered field can interpret syntax that a rich-text field displays literally.
What to do: Agree on the editor controls and conventions used for each field. Test examples in the actual Jira project before sharing a team template.
Challenge: Long descriptions hide the important details
Why it happens: Several topics are placed in one paragraph, forcing reviewers to read everything before they find the steps or expected result.
What to do: Use short sections with descriptive headings. Put reproduction actions in a numbered list and keep background information separate.
Challenge: Pasted content carries messy styling
Why it happens: Text copied from another editor may bring inconsistent fonts, spacing, or list styles into Jira.
What to do: Paste as plain text when possible, then format it with Jira’s own controls. Preview the result before submitting a detailed issue.
Challenge: Code snippets are difficult to read
Why it happens: Normal paragraphs can collapse spacing or make code blend into the surrounding explanation.
What to do: Use a code-block control or the syntax supported by that field. Add a short label explaining what the snippet shows, such as “Error returned after saving.”
FAQs
Does Jira support Markdown?
Jira’s formatting support depends on the editor and field. The current rich-text editor offers formatting controls and may support familiar keyboard shortcuts. Some older Jira environments or fields configured with a wiki renderer accept Jira wiki markup. Markdown characters are not guaranteed to work everywhere, so test the syntax in the field you plan to use or apply formatting through the toolbar.
Why does my Jira text show asterisks instead of bold?
The field may not interpret wiki markup. In a rich-text editor, entering *bold* can leave the asterisks visible instead of applying bold styling. Select the text and use the bold control, or check whether the field uses a wiki renderer. If other fields behave differently, ask your Jira administrator whether their renderer settings differ.
How do I add a code block in Jira?
Look for a code or code-block option in the rich-text toolbar. In environments that support wiki markup, a code block may use syntax such as {code}your code here{code}. The exact options can vary by Jira version and field. Use a code block for multi-line snippets, and provide a brief explanation so readers know what the example demonstrates.
Can I use Jira formatting in comments as well as descriptions?
Often, comments and descriptions offer similar rich-text controls, but the available formatting can differ by Jira version and configuration. Check the toolbar in each field rather than assuming the same markup will work in both. If you are creating a team convention, test it in a comment and a description before asking everyone to follow it.
What is the clearest way to format a bug report?
Start with a concise summary, then separate the environment, reproduction steps, expected result, and actual result. Use numbered steps for actions someone should repeat, and reserve code blocks for exact error messages or technical snippets. This structure gives a reviewer a useful path to reproduce the problem without digging through unrelated background.
Conclusion
Clear Jira formatting starts with a simple check: identify the editor and field you are using. Apply rich-text controls in the current editor, and use wiki markup only where the field supports it.
Then organize the content around the reader’s task. Headings, numbered reproduction steps, descriptive links, and readable code blocks can make an issue easier to review and act on.
When formatting symbols appear literally or pasted text looks inconsistent, test the field and use its native controls. A few clear conventions can prevent confusion and keep Jira pages useful for the whole team.