Obsidian Confluence Integration Plugin is an open-source plugin for Obsidian.md that allows you to publish markdown content from Obsidian to Atlassian Confluence. It supports Obsidian markdown extensions for richer content and includes a CLI for pushing markdown files from the command line. Currently, the plugin only supports Atlassian Cloud instances.

Getting Started: Publishing and Moving Pages

This section provides a brief overview of the recommended workflow for publishing pages using the Confluence Integration plugin for Obsidian and how to move the published pages in Confluence if necessary.

Publishing Pages

Install and configure the Confluence Integration plugin for Obsidian. Ensure that you have provided the required API credentials and settings.
Organize your files and folders within your Obsidian vault according to your desired Confluence structure.
Use YAML frontmatter to customize page properties, such as connie-title, tags, and connie-frontmatter-to-publish, as needed.
Publish your pages by running the publish command provided by the Confluence Integration plugin. The plugin will upload your pages and files, maintaining the folder structure and hierarchy defined in your Obsidian vault.

Moving Pages in Confluence

If you need to move a page or a folder within Confluence, follow these steps:

In Confluence, navigate to the page you want to move.
Click the ellipsis (three dots) in the upper right corner of the page and select Move from the dropdown menu.
Choose the new parent page or Space where you want to move the page.
In Obsidian, update the corresponding file's YAML frontmatter with the connie-dont-change-parent-page property set to true. This will prevent the Confluence Integration plugin from moving the page back to its original location when matching the local file tree.

Example:
```
---
connie-dont-change-parent-page: true
---
```
If you are moving an entire folder, ensure you have a Folder Note for the folder and add the connie-dont-change-parent-page property to the Folder Note as well.
Run the publish command in Obsidian to update the pages with the new frontmatter settings.

By following this workflow, you can effectively publish and manage your pages in Confluence while maintaining the organization and structure of your Obsidian vault.

Installation

Install the confluence-integration plugin from Obsidian's community plugins browser.
Open the plugin settings and configure the following fields:
- Confluence Base URL: The base URL of your Atlassian Confluence instance (e.g., https://your-domain.atlassian.net)
- Confluence Parent Id: The Confluence page ID where your notes will be published as child pages
- Atlassian User Name: Your Atlassian account's email address
- Atlassian API Token: Your Atlassian API token. You can generate one from your Atlassian Account Settings.
- Folder To Publish: The name of the folder in Obsidian containing the notes you want to publish (default: "Confluence Pages")

Installing plugin using Obsidian42-BRAT

To install the confluence-integration plugin using Obsidian42-BRAT, follow these steps:

Adding a beta plugin

Install BRAT from the Community Plugins in Obsidian.
Get the link to the GitHub repository you want to test. The plugin developer can provide you with this link. For the confluence-integration plugin, use this link: https://github.com/markdown-confluence/obsidian-integration
Open the command palette and run the command BRAT: Add a beta plugin for testing
Using the link from step 2, copy that into the modal that opens up.
Click on Add Plugin -- wait a few seconds and BRAT will tell you what is going on.
After BRAT confirms the installation, in Settings go to the Community plugins tab.
Refresh the list of plugins.
Find the beta plugin you just installed (confluence-integration) and Enable it.

Updating beta plugins

Plugins can be updated using the command palette by running the command Check for updates to all beta plugins and UPDATE.
Optionally, beta plugins can be configured to auto-update when starting Obsidian. This feature can be enabled in the Obsidian42- BRAT tab in settings.

Currently not everything in Obsidian is supported but slowly increasing support where possible over time.

Comment Handling

This plugin attempts to find the original location of a comment and reattach it. If it cannot determine the correct location, it will add a section to the bottom of the page and place the comment there.

Comment Matching Process

No matches found

If no matches for the text the comment was attached to are found, the comment is moved to the unmatched comment section.

Exact Match

The plugin first tries to find an exact match for the comment by comparing the text before and after the comment. If an exact match is found, the comment is attached at that location.

Distance of whole before and after

If an exact match is not found, the plugin calculates the "distance" between the text before and after the comment in the original location and each potential new location. This distance is calculated using the Levenshtein distance algorithm, which measures the number of changes (insertions, deletions, or substitutions) required to transform one string into another. If there are more than 40 changes before and after the comment text the node is excluded from being a viable option. The potential matches are sorted based on the calculated distances, and the match with the smallest distance is chosen.

Distance of 2 words before and after

If there are still multiple matches with similar distances, the plugin narrows down the selection by comparing only the words immediately surrounding the comment. The Levenshtein distance is calculated again, and the best match is chosen based on the smallest distance.

No ability to match

If no suitable match is found, the function returns undefined.

Flow chart

flowchart TD
    Start --> DoesCommentTextExist{Does comment text exist on page?}
    DoesCommentTextExist -->|Yes| DoesExactMatchExist{Does exact match before and after comment text?}
    DoesCommentTextExist -->|No| UnmatchedCommentSection[Unmatched Comment Section]
    DoesExactMatchExist -->|Yes| AttachComment[Attach Comment To This ADF Node]
    DoesExactMatchExist -->|No| CalculateLevenshtein

    subgraph WholeBeforeAfter
        CalculateLevenshtein[Calculate Levenshtein Distance Between Before and After text] --> SortByMinimumDistance[Sort by minimum distance]
        SortByMinimumDistance --> IsFirstItemMinimumDistanceUnder40{Is first item minimum distance under 40 changes?}
    end

    IsFirstItemMinimumDistanceUnder40 -->|Yes| AttachComment
    IsFirstItemMinimumDistanceUnder40 -->|No| GetXWordsBeforeAfterComment[Get X Words before and after comment]

    subgraph WordsBeforeAfter
        GetXWordsBeforeAfterComment --> TrimBeforeAndAfterToSameLength
        TrimBeforeAndAfterToSameLength --> CalculateWordsLevenshtein
        CalculateWordsLevenshtein --> IsDistanceLessThan50percentCharacters{IsDistanceLessThan50percentCharacters}
        IsDistanceLessThan50percentCharacters -->|Yes| AddToChecks
        IsDistanceLessThan50percentCharacters -->|Yes| CalculateWordsLevenshtein
        IsDistanceLessThan50percentCharacters -->|No| CalculateWordsLevenshtein
        AddToChecks --> SortByWordsMinimumDistance
        SortByWordsMinimumDistance --> IsThereAnyItems{IsThereAnyItems}
    end

    IsThereAnyItems -->|Yes| AttachComment
    IsThereAnyItems -->|No| UnmatchedCommentSection

Supported Markdown Features

The Confluence Integration plugin for Obsidian supports a variety of Markdown features, allowing you to create rich and interactive content in your Confluence pages. The following Markdown elements are supported:

Blockquotes

Blockquotes are supported and can be created using the > character followed by the text you want to quote.

Callouts

Callouts can be created using the Callouts feature, which allows you to create custom, styled callout boxes in Confluence.

Code

Code blocks and inline code can be created using triple backticks (```) for blocks and single backticks (`) for inline code.

Diagrams (Mermaid.js)

Mermaid.js diagrams are supported through the plugin's Mermaid diagram feature, which renders diagrams as images in Confluence.

Images (Image Upload Supported)

Image embedding and uploading are supported through the Image Upload feature. Images included in a page will be uploaded as attachments in Confluence. This includes support for transcluded images.

Linking

Wikilinks: The plugin supports basic Wikilinks functionality, allowing you to link to other files that are being published.
Extenal links: Rendered as a Smart Link

Headings

Headings can be created using the # character followed by the heading text. Multiple levels of headings can be created by using multiple # characters.

Horizontal Bar

Horizontal bars can be created using three hyphens (---).

Lists

Both ordered and unordered lists can be created using Markdown syntax.

Text Formatting

Strike-through: Text can be formatted with strike-through using double tildes (~~).
Emphasis: Emphasis can be added using single (*) or double (**) asterisks for italic and bold formatting, respectively.

Tables

Tables can be created using Markdown syntax with pipes (|) and hyphens (-) to define the table structure.

Callouts

Callouts can be created using the Callouts feature. This allows you to create custom, styled callout boxes in Confluence.

Folder Notes

The Folder Note feature allows you to define and manage the content for the "Folder" in Confluence by creating a file directly in the folder with the same name as the folder. This feature ensures that the file is not uploaded as a child of the page in Confluence, but instead becomes the page under which other files are uploaded.

Usage

In your Obsidian vault, create a file directly within the folder you want to manage in Confluence. The file should have the same name as the folder.
Add your desired content to the file, which will be used to represent the folder in Confluence.
When you publish your files using the Confluence Integration plugin, the file will be uploaded to Confluence as the folder representation, and other files within the folder will be uploaded as child pages underneath it.

Benefits

By utilizing the Folder Note feature, you can achieve the following benefits:

Maintain a clear and organized folder structure in Confluence that matches your Obsidian vault.
Easily manage the content and hierarchy of your pages in Confluence.
Move a folder of files to a new Space in Confluence.
Seamlessly upload files as child pages underneath the corresponding folder representation in Confluence.

Obsidian Use

You can use this feature in Obsidian using the Obsidian folder notes plugin.

Folder Structure

The folder structure feature is designed to help you easily manage and organize your files when they are published to Confluence. The plugin will identify the first common folder and match the folder structure in your local Obsidian vault in Confluence. This also ensures the plugin will move pages on Confluence to align with your local file layout.

Usage

When you publish your files, the plugin will automatically find the first common folder and upload the files according to that folder structure.

Preventing Pages from Moving

If you don't want a specific page to be moved or you want to move a Confluence page outside of your page tree into another Space, you can use the connie-dont-change-parent-page tag. This will prevent the plugin from moving the page back to the file tree where it would expect the page to live when matching the local file tree.

---
connie-dont-change-parent-page: true
---

Moving a Folder with Folder Note

You can use the folder structure feature in conjunction with the Folder Note feature to move a whole folder of files to a new location in Confluence. By adding the connie-dont-change-parent-page tag to the Folder Note, you can prevent the pages within the folder from being moved back to their original locations in the file tree.

Image Upload

The Image Upload feature ensures that any images included in a page are uploaded as attachments for that specific page in Confluence. This means that if the same image is used in multiple pages, it is uploaded into each respective page as an attachment.

Preventing Duplicate Image Uploads

In order to avoid retrieving the image from Confluence every time the publish process is run, the plugin uses the hash (MD5) of the image file contents and stores it as a comment on the attachment. This ensures that images are uploaded only once per page and are updated only when the contents change.

To prevent conflicts with file names when uploading images to Confluence, the plugin uses the following naming convention for the uploaded images:

${Absolute Path MD5}-${Filename without path}

This naming convention helps to avoid conflicts and ensures that each uploaded image has a unique identifier.

Limitations

Currently, the Confluence Integration plugin does not support deleting images from Confluence.

References

Mermaid Diagram Support

As Confluence does not currently support Mermaid diagrams natively, the Confluence Integration plugin for Obsidian provides a workaround to enable the rendering of Mermaid diagrams. The plugin includes a copy of Mermaid that is injected into a BrowserWindow, which is then used to render each diagram and capture a screenshot as a PNG image. This image is then uploaded to Confluence for rendering.

Usage

Create a Mermaid diagram in your Obsidian note using the appropriate syntax.

Insert example here

When you publish your files using the Confluence Integration plugin, the plugin will automatically render the Mermaid diagram, capture a screenshot, and upload it as a PNG image to Confluence.

Insert example here

Naming Convention

To prevent conflicts with file names when uploading diagrams to Confluence, the plugin uses the following naming convention for the uploaded diagram images:

RenderedMermaidChart-${MD5 of diagram text}.png

This naming convention helps to avoid conflicts and ensures that each uploaded diagram image has a unique identifier.

Limitations

Currently, the Confluence Integration plugin does not support deleting diagram images from Confluence.

YAML Frontmatter Support

The Confluence Integration plugin for Obsidian supports various YAML frontmatter items, allowing you to customize and modify how the publish process works.

connie-title

This item allows you to override the title of the Confluence page without renaming the Obsidian file.

Example

---
connie-title: New Title
---

connie-frontmatter-to-publish

This item is set to an array of frontmatter keys that you want to include in a table at the beginning of the document.

Example

The example below will include four rows in the Frontmatter table at the beginning of the document.

---
array-singleline:
  - testing
  - testing
array-multiline:
  - testing tag1
  - testing tag2
string: Testing
boolean-value: true
connie-frontmatter-to-publish:
  - array-singleline
  - array-multiline
  - string
  - boolean-value
---

connie-page-id

This item specifies the Confluence Page ID that the file will be uploaded to. It is set for every file. If it is not set when you publish a file, it will be assigned after the page has been created for that file in Confluence.

Example

---
connie-page-id: "12312"
---

connie-dont-change-parent-page

If you want to move a Confluence page outside of your page tree and into another Space, you can use this item to prevent the page from being moved back to the file tree where the plugin would expect the page to be when matching the local file tree. When used with the Folder Note feature, you can move an entire folder of files to a new location in Confluence.

Example

---
connie-dont-change-parent-page: true
---

Callouts

The Callouts feature allows you to transform Markdown callouts, also known as admonitions, into Atlassian Document Format (ADF) Panels. This feature supports both normal and foldable callouts.

Normal Callouts

Normal callouts are converted to Panels in Confluence.

Example:

> [!note]
> Lorem ipsum dolor sit amet

Foldable Callouts

Foldable callouts are converted to Expand Macros in Confluence. Note that Expand Macros do not support the same colors and formatting that Panels do.

Example:

> [!faq]- Are callouts foldable?
> Yes! In a foldable callout, the contents are hidden when the callout is collapsed.

Nested Callouts

Due to Confluence restrictions, nested callouts are not supported.

Supported Features

Title
Types: Refer to the supported types
Foldable

For more information on Obsidian callouts, visit the Obsidian documentation.

Wikilinks Support

The Confluence Integration plugin for Obsidian offers basic support for Wikilinks. This support is limited to linking to other files that are being published. If a Wikilink refers to a page that is not set to be published, the link will be removed during the publishing process and will be rendered as plain text in Confluence.

Wikilinks can be used to connect pages within a single Confluence site, including across multiple spaces.

When using Wikilinks, the plugin supports three ways to provide information about the link:

Link to Page

[[Page To Link To]]

This syntax creates a smart link to the specified page, displaying the page title and image.

Link to Header

[[Page To Link To#Header]]

This syntax creates a smart link to the specified page, displaying the page title and image. The link will point to a specific header within the page.

Alias

[[Page To Link To|Alias To Display]]
[[Page To Link To#Header|Alias To Display]]

This syntax allows you to define an alias for the link, which will be displayed instead of the original page title or header. The link will be rendered as regular text that points to the specified page and header (if included).

Thank you

Thanks for a great library for interacting with the Confluence api and also for being responsive to questions and contributions https://github.com/MrRefactoring/confluence.js
Atlassian teams, for Open Sourcing libraries that helped enable this project. Some packages that are used but not all.
- Render ADF in React https://atlaskit.atlassian.com/packages/editor/renderer
- Convert Prosemirror to ADF https://atlaskit.atlassian.com/packages/editor/editor-json-transformer
- Convert Markdown to Prosemirror (The Markdown transformer used was based on code originally from the NPM package) https://atlaskit.atlassian.com/packages/editor/editor-markdown-transformer
- traverse is used extensively to mutate ADF elements https://atlaskit.atlassian.com/packages/editor/adf-utils
Markdown-it is the core Markdown parser https://github.com/markdown-it/markdown-it

Changelog

5.3.0 (2023-05-11)

Features

Move ImageUpload and MermaidRendering to plugins to allow for more plugins easily (cfae670)

Obsidian Confluence Integration

5.3.0 (2023-05-11)

5.2.6 (2023-05-11)

5.2.5 (2023-05-10)

5.2.4 (2023-05-10)

5.2.3 (2023-05-10)

5.2.2 (2023-05-10)

5.2.1 (2023-05-10)

5.2.0 (2023-05-09)

5.1.0 (2023-05-09)

5.0.1 (2023-05-03)

5.0.0 (2023-05-03)

4.9.0 (2023-04-30)

4.8.0 (2023-04-30)

4.7.5 (2023-04-30)

4.7.4 (2023-04-29)

4.7.3 (2023-04-29)

4.7.2 (2023-04-28)

4.7.1 (2023-04-28)

4.7.0 (2023-04-28)

4.6.4 (2023-04-28)

4.6.3 (2023-04-28)

4.6.2 (2023-04-28)

4.6.1 (2023-04-28)

4.6.0 (2023-04-28)

4.5.0 (2023-04-28)

4.4.0 (2023-04-27)

4.3.0 (2023-04-27)

4.2.8 (2023-04-26)

4.2.7 (2023-04-26)

4.2.6 (2023-04-26)

4.2.5 (2023-04-26)

4.2.4 (2023-04-26)

4.2.3 (2023-04-26)

4.2.2 (2023-04-26)