Sharp Markdown for Confluence and Jira: documentation
Sharp Markdown lets you write and edit Confluence and Jira content in Markdown. There are two apps with the same Markdown engine: Sharp Markdown for Confluence and Sharp Markdown for Jira. Install the one for the product you use, or both.
Markdown is plain text with simple marks for formatting, such as **bold** and # Heading. The apps use GitHub Flavored Markdown: https://github.github.com/gfm/
Confluence: the Markdown macro
- Edit a page, type
/Sharp Markdownand choose Sharp Markdown. - The editor opens. Write Markdown on the left. The preview on the right updates while you type. On a narrow screen, switch between Write and Preview.
- The toolbar adds headings, bold, italic, links, code, lists, task lists, tables and note panels.
- Select Save, and publish the page.
To change the Markdown later, edit the page, select the macro and choose the edit (pencil) button.
The macro shows:
- headings, bold, italic, strikethrough, links, lists, task lists, tables, quotes and footnotes
- note panels written as
> [!NOTE],> [!TIP],> [!IMPORTANT],> [!WARNING]and> [!CAUTION], in the colours of Confluence panels - code blocks with highlighting for 27 languages, such as JavaScript, Python, Java, SQL, YAML and Bash
- Mermaid diagrams from code blocks with the language
mermaid
Raw HTML is not shown, except <br>, <u>, <sub>, <sup> and <details>. Images in the macro are shown as links, because Confluence doesn’t allow apps to load images from other websites.
Confluence search finds the text of the macro. PDF and Word exports show the macro as normal page content: headings, tables, task lists, panels and code. A Mermaid diagram is exported as its code, because the diagram can’t be drawn during an export.
Confluence: Edit in Markdown
- On a page, open the ••• menu and choose Apps and Edit in Markdown.
- The whole page opens as Markdown with a preview.
- Edit the text and select Save. The page is saved as a new version, and page history keeps the earlier versions.
Markdown can’t show everything a Confluence page can hold. Those items appear as purple markers, such as ⟦#3 @Ann⟧, and come back unchanged when you save:
- mentions, statuses, dates, emojis and smart links
- macros, images and attachments
- text colour, underline and inline comments around the text they cover
- expands, layouts and custom panels, with their content as normal Markdown between an opening and a closing marker
A marker can’t be edited in part: the cursor jumps over it, and deleting removes the whole marker. If you delete a marker, the app lists the items before saving and asks you to confirm. If a marker is broken, for example an opening marker without its closing marker, nothing is saved and the app tells you which marker to fix.
Info, success, note, warning and error panels become > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] and > [!CAUTION]. Tables with a header row become Markdown tables and keep their column widths when you don’t add or remove tables. Tables with merged cells or lists inside cells are kept as one marker.
If someone else saves the page while you edit, your changes are not saved over theirs. Copy your Markdown with Copy my Markdown, close the window and open it again.
Confluence: Copy and export
- Copy as Markdown (••• → Apps) copies the page as Markdown, for example for an AI chat. Images and attachments become links to the page.
- Export as Markdown shows the page and its child pages. Choose a page and select Export page, or Export page and child pages (.zip) for the whole tree. Up to 500 pages are exported at a time.
The .zip keeps the page tree:
- each page is a file
Page title.md, and its child pages are in the folderPage title/ - when a page has several child pages, the files are numbered (
01 Design.md) to keep the Confluence order - images and files used on the pages are in the folder
_attachments/ - links between the exported pages become relative links between the files
- with Front matter on, each file starts with the page title, page ID and address
A single page without images is downloaded as a .md file.
Confluence: Import Markdown
- Open the page under which the new pages should go, open ••• and choose Apps and Import Markdown.
- Choose Markdown files, a folder, or a .zip file.
- Check the page tree, the attachments and the notes. Nothing is created yet.
- Select Import (the button shows the number of pages).
How the files become pages:
- Each .md file becomes a page. The title is the
titlein the front matter, otherwise the first#heading, otherwise the file name. A number prefix such as01-is left out of the title. - A folder becomes a parent page. Its
README.mdorindex.mdis the content of that page; without one, the parent page is empty. A fileGuide.mdnext to a folderGuide/is the page of that folder, as in an export. - If all files are in one folder, such as
repo-main/in a .zip from GitHub, that folder is skipped. - Pages are sorted by file name, so 2 comes before 10.
- Images and files that a page links to with a relative path are attached to the page. Links to other imported files point to the new pages.
- Confluence needs unique page titles in a space. A title that already exists gets a number, such as
Guide (2), and the import tells you before it starts.
The pages are created with your account, so page history shows your name. Each page is created as a draft, its attachments are added, and then it is published, so each page gets one version. If a page fails, the import continues and lists the pages that failed.
Jira: Markdown in issues
The actions are in the ••• menu of an issue:
- Edit description in Markdown opens the description as Markdown with a preview. Mentions and other items that Markdown can’t show are purple markers, as in Confluence. If someone else changes the issue while you edit, the save stops.
- Comment in Markdown saves Markdown as a normal Jira comment, with headings, tables, task lists and code. It suits answers pasted from AI tools. Mentions are made in Jira’s own editor.
- Copy issue as Markdown copies the summary, key fields, description and comments, or downloads them as a .md file.
Jira shows earlier descriptions in the issue history as wiki markup, such as h2. and {code}. When you paste wiki markup into the editor, the app offers to convert it to Markdown. The Wiki markup button converts text you paste into its box.
The actions work in the Jira issue view. They are not in the Jira Service Management customer portal or the mobile apps.
Light and dark mode
The apps follow the colour mode of Confluence and Jira.
Good to know
- Everything runs in your browser with your own permissions, so the apps show and change only what you can.
- If your license isn’t active, the macro shows its Markdown as plain text, so no content is lost.
Data and permissions
- Confluence: reading and saving pages, reading child pages and reading and adding attachments, all with the permissions of the person who uses the app.
- Jira: reading and saving issue content (
read:jira-work,write:jira-work) with the permissions of the person who uses the app. - The apps have no external connections and no storage of their own. Privacy policy: https://hdsoft.fi/en/products/atlassian/sharp-markdown/privacy/
Support
Email support@hdsoft.fi. Support hours, response times and security reports: https://hdsoft.fi/en/products/atlassian/support/
