Markdown to Confluence Tools

Hello there, Markdown aficionados and Confluence connoisseurs! We're excited to introduce you to the markdown-confluence project, a seamless solution that bridges the gap between the elegant simplicity of Markdown and the powerful flexibility of Confluence. We understand your passion for the ease and convenience of Markdown writing, and we're committed to ensuring you can continue to enjoy it while effortlessly publishing your content on Confluence.

Our suite of tools, including an Obsidian plugin, npm CLI, Docker CLI, GitHub Action, and npm library, enables you to smoothly convert your Markdown files to Atlassian Document Format (ADF) and integrate them seamlessly with Confluence.

The markdown-confluence project was born from the desire to simplify the publishing process, making it a delightful experience for Markdown enthusiasts who also work with Confluence. We believe that the best tools should make life easier and more enjoyable. That's why we've designed an opinionated, streamlined workflow that makes the publishing process a breeze, while still allowing for customization and flexibility. Obsidian.md is our recommended editor, but have no fear! Our tools are compatible with any Markdown files, so you're free to choose the setup that suits you best.

As we dive into the wonderful world of markdown-confluence, we're eager to grow a vibrant community around this project and are thrilled to have you as part of this adventure. We envision a future where our users not only appreciate the simplicity and efficiency of our tools but also find joy in sharing ideas, collaborating, and contributing to the project. So, go ahead and give markdown-confluence a spin! Experience firsthand how it can revolutionize your Markdown-to-Confluence workflow. And remember, we're here to support you every step of the way, making sure your journey into the delightful universe of markdown-confluence is nothing short of amazing! 🎉

Further Resources

In this documentation, we have explored various aspects of the Markdown-Confluence project. Below, you will find quick summaries and links to each section for easy reference.

Github Org - This is the main organization page on GitHub for the Markdown-Confluence project, where you can find all related repositories and ongoing development efforts.
Github mono repo - This is the mono repository for the Markdown-Confluence project, containing the core source code and modules for the project's functionality.
Edit docs - This repository houses the editable Markdown source files for the documentation, where you can contribute to or edit the project documentation directly.
Docs rendered in Confluence - View the fully rendered documentation within the Confluence platform, providing a comprehensive and navigable guide for using the Markdown-Confluence project.

Usage

This is about the usage of the tools

NPM CLI

This tool is designed to make the process of publishing documentation to Confluence faster, more streamlined, and more efficient. It supports multiple authentication methods and allows you to publish your Markdown files to any Confluence space or page of your choice.

With its user-friendly and clear documentation, this tool is accessible to everyone, regardless of their technical expertise. Whether you're a software developer, technical writer, or project team member, this CLI tool is a game-changer for anyone who needs to publish documentation to Confluence.

Configuration

Setting up the configuration for an application is an essential step to ensure its proper functioning. For non-technical users, it is important to understand the basics of managing settings. Generally, there are two types of settings you'll need to work with: non-sensitive values and sensitive values.

For non-sensitive values like the website's address, page identifiers, your username, or the folders you're working with, using a configuration file is the preferred method. A configuration file is a simple, organized, and user-friendly way to store settings. You don't need technical expertise to manage it, as the settings are typically listed in a readable format. By keeping these settings in a separate file, you can easily find and change them whenever needed without worrying about breaking the application.

Sensitive values, such as API tokens or passwords, should be handled with more care. Instead of storing them in a configuration file, it's recommended to use environment variables. Environment variables are a secure way to store sensitive information because they are accessible only to the application when needed and not exposed to others. As a non-technical user, you may need assistance from a technical team member or follow step-by-step instructions provided by the application to set up environment variables. By separating your settings into non-sensitive and sensitive categories and storing them appropriately, you can help ensure your application runs smoothly and securely.

Example setup

.markdown-confluence.json

{
    "confluenceBaseUrl": "https://markdown-confluence.atlassian.net",
    "confluenceParentId": "524353",
    "atlassianUserName": "andrew.mcclenaghan@gmail.com",
    "folderToPublish": "."
  }

Environment Variables

macOS / Linux

export ATLASSIAN_API_TOKEN="YOUR API TOKEN"

Windows

set ATLASSIAN_API_TOKEN="YOUR API TOKEN"

https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1

CLI Command

npx @markdown-confluence/cli

Docker Image

The ghcr.io/markdown-confluence/publish:latest Docker image is a ready-to-use container that wraps up the npm CLI and has the same arguments. By using this Docker image, you can quickly start publishing your Markdown files to Confluence without the need to set up the npm CLI tool manually.

Usage

To use the ghcr.io/markdown-confluence/publish:latest Docker image, follow these steps:

Create a .markdown-confluence.json configuration file in your project directory as described in the "Example setup" section above.
Set up environment variables for sensitive information like the Atlassian API token.
Run the Docker container using the following command:

docker run -it --rm -v "$(pwd):/content" -e ATLASSIAN_API_TOKEN ghcr.io/markdown-confluence/publish:latest

This command does the following:

-it: Runs the Docker container interactively, allowing you to see the output and interact with the running process if necessary.
--rm: Removes the container once the process has completed.
-v "$(pwd):/content": Maps your current working directory (where your configuration file and Markdown files are located) to the /content volume inside the container. This allows the container to access your files.
-e ATLASSIAN_API_TOKEN: Loads environment variables from the current console.

Example setup

.markdown-confluence.json

{
    "confluenceBaseUrl": "https://markdown-confluence.atlassian.net",
    "confluenceParentId": "524353",
    "atlassianUserName": "andrew.mcclenaghan@gmail.com",
    "folderToPublish": ".",
  }

Environment Variables

macOS / Linux

export ATLASSIAN_API_TOKEN="YOUR API TOKEN"

Windows

set ATLASSIAN_API_TOKEN="YOUR API TOKEN"

https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1

Updating the Docker Image

To update the Docker image to the latest version, run the following command:

docker pull ghcr.io/markdown-confluence/publish:latest

This command fetches the latest version of the ghcr.io/markdown-confluence/publish:latest Docker image and replaces the existing one on your system.

Conclusion

By using the ghcr.io/markdown-confluence/publish:latest Docker image, you can quickly and easily publish your Markdown files to Confluence without any additional setup. With its straightforward configuration and seamless integration with Docker, this tool is a valuable resource for anyone who needs to work with Confluence and Markdown files.

markdown-confluence/publish GitHub Action

This GitHub Action wraps up an NPM CLI that allows you to publish your Markdown files to Confluence quickly and easily. By using this action in your workflows, you can automate the process of publishing documentation to Confluence, making it faster, more streamlined, and more efficient.

Usage

To use this GitHub Action in your repository, you'll need to create a workflow file (e.g., .github/workflows/publish.yml) and configure the action as described below.

Basic example

name: Publish to Confluence
on: push

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      
      - name: Publish Markdown to Confluence
        uses: markdown-confluence/publish@v1
        with:
          confluenceBaseUrl: https://your-confluence-instance-url
          confluenceParentId: 123456
          atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }}
          atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}

Example using a config file

Create a .markdown-confluence.json file in your repository with the following content:

{
  "confluenceBaseUrl": "https://your-confluence-instance-url",
  "confluenceParentId": "123456",
  "atlassianUserName": "your-email@example.com",
  "folderToPublish": "docs",
  "contentRoot": "/docs"
}

Then configure the GitHub Action in your workflow file:

name: Publish to Confluence
on: push

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      
      - name: Publish Markdown to Confluence
        uses: markdown-confluence/publish@v1
        with:
          configFile: .markdown-confluence.json
          atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}

Input Options

This section provides an overview of all the input options available for the markdown-confluence/publish GitHub Action and examples of how to use them in your workflows.

confluenceBaseUrl

The base URL of your Confluence instance, used for API calls and publishing content. This value should include the protocol (e.g., https://) but not a trailing slash.

Example:

with:
  confluenceBaseUrl: https://your-confluence-instance-url

confluenceParentId

The ID of the parent page in Confluence where the Markdown files will be published as child pages.

Example:

with:
  confluenceParentId: 123456

atlassianUserName

Your Atlassian account's username, required for authentication when interacting with Confluence.

Example:

with:
  atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }}

atlassianApiToken

An API token generated for your Atlassian account, used for authentication when making API calls to Confluence. This value should be stored as a repository secret.

Example:

with:
  atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}

folderToPublish

The folder you want to apply a default of "connie-publish: true" to. All Markdown files within this folder will be considered for publishing.

Example:

with:
  folderToPublish: docs

contentRoot

The root path for published content on Confluence. This is used to tell the action where to look for Markdown files and content.

Example:

with:
  contentRoot: /docs

configFile

A configuration file containing additional settings and customizations for the publishing process. You can use this option to keep your workflow file clean and maintain all configuration settings in a separate file.

Example:

with:
  configFile: .markdown-confluence.json

Advanced Example

Here's an example of using all input options in a single workflow:

name: Publish to Confluence
on: push

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      
      - name: Publish Markdown to Confluence
        uses: markdown-confluence/publish@v1
        with:
          confluenceBaseUrl: https://your-confluence-instance-url
          confluenceParentId: 123456
          atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }}
          atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }}
          folderToPublish: docs
          contentRoot: /docs
          configFile: .markdown-confluence.json

Remember to create and configure the .markdown-confluence.json file in your repository as needed.

Storing API token as a repository secret

To store your Atlassian API token as a repository secret, follow these steps:

Go to your GitHub repository and click on the "Settings" tab.
In the left sidebar, click on "Secrets".
Click on the "New repository secret" button.
Enter ATLASSIAN_API_TOKEN as the name and paste your API token as the value.
Click on the "Add secret" button.

Now you can reference the ATLASSIAN_API_TOKEN secret in your GitHub Actions workflows using the syntax ${{ secrets.ATLASSIAN_API_TOKEN }}.

Support

If you need help with using this action or encounter any issues, please open an issue in the GitHub repository.

License

This GitHub Action is released under the Apache 2.0 License.

NPM Library Documentation

Please log an issue with what documentation you require

❄️ The Frosty Chronicles of Markdown to Atlassian Document Format Conversion ❄️

Hello, friends, it's me again - Olaf! And boy, do I like warm hugs! But today, we're venturing a bit away from the land of warmth and into the magical frosty realm of converting Markdown to Atlassian Document Format (ADF) using the @markdown-confluence/lib function. Just like a good snowfall, this might seem a bit overwhelming at first, but don't worry, I'll guide you through it all.

🎇 Spellcasting 101: `parseMarkdownToADF`

Our journey begins with our first spell, parseMarkdownToADF. This enchanting piece of incantation transforms the everyday language of Markdown into the mysterious tongue of ADF. It requires two ingredients: a string of markdown and a confluenceBaseUrl.

const magicalMarkdown = "# Welcome to Arendelle";
const confluenceBaseUrl = "https://arendelle.atlassian.net/wiki";

let adfNodes = parseMarkdownToADF(magicalMarkdown, confluenceBaseUrl);

Just like that, it conjures up a flurry of nodes which are then delicately shaped into a format that our friends at Atlassian can understand. Now that we've whipped up our magic snowstorm, let's step back and admire our handiwork.

🎇 Transmutation Magic: `convertMDtoADF`

After our initial spellcasting, we have another magical formula to share. This one's called convertMDtoADF and it's quite the spectacle. Unlike our previous enchantment, this spell takes an entire Markdown file and some Confluence settings to create a grand ADF spectacle.

const markdownFile: MarkdownFile = {
  contents: "# Welcome to Arendelle",
  ...
};

const confluenceSettings: ConfluenceSettings = {
  confluenceBaseUrl: "https://arendelle.atlassian.net/wiki",
  ...
};

let adfFile = convertMDtoADF(markdownFile, confluenceSettings);

And just like that, our Markdown file is transformed into an ADF masterpiece, ready to take center stage on our Confluence platform.

Our magical journey is complete, dear friends. But remember, the joy is in the journey, not the destination. So don't be afraid to practice your spells, make a few mistakes, and get a bit frosty in the process. The magic of transformation is all around us, and with these spells, you're well on your way to becoming a true snow wizard!

And don't forget - warm hugs make the journey all the more magical. 🤗

Obsidian Plugin Usage

Go to https://obsidian-confluence.com for usage information.

Features

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 Uploads: Bedrock's Picto-Rama: Rockin' Pages with Dino-Sized Fun

Unleash your inner caveman and include images in your markdown-confluence pages with both wikilinks and regular markdown styles. They'll search high and low for the right file, just like a hungry dinosaur on the hunt.

Here are the two markdown formats for adding images:

![[cave_painting.png]]

![](images/dinosaur.png)

Paths for these images are always relative to the markdown file they're in, so you'll never lose your way in the Bedrock wilderness.

Need to grab a file from another folder? Use ../ like this:

![](../other_cave/images/sabertooth.png)

Dino-Sized Attachments Adventure

Whoa, hold onto your dino-sized hats! When you add images to a page, they'll hitch a ride as attachments for that specific page in Confluence, just like a pterodactyl flying through the sky. And if the same image struts its stuff on multiple pages, it'll be attached to each one, spreading prehistoric cheer all around!

No More Duplicate Dino Images!

To avoid fetching the image from Confluence every time you run the publish process, our plugin uses the hash (MD5) of the image file and stores it as a comment on the attachment. This way, images are only uploaded once per page and updated only when the contents change.

To prevent name clashes when uploading images to Confluence, we use this unique naming convention:

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

This ensures each image has a unique identifier, just like a dino's footprint.

Limitations

Currently, our Confluence Integration plugin can't delete images from Confluence. But hey, neither could Fred Flintstone!

References

Now you're ready to make your documentation a modern Stone Age masterpiece!

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).

Settings Loaders

This document describes the different settings loaders used to load and merge settings for the ConfluenceSettings configuration object. Each loader is responsible for loading settings from a specific source, and they can be combined to create a merged configuration.

DefaultSettingsLoader

Purpose: Load default settings from the DEFAULT_SETTINGS object.

Settings source: DEFAULT_SETTINGS object.

Example:

const defaultLoader = new DefaultSettingsLoader();
const defaultSettings = defaultLoader.loadPartial();

StaticSettingsLoader

Purpose: Load settings provided as a static object.

Settings source: User-provided object.

Example:

const staticSettings = {
  confluenceBaseUrl: "https://example.com",
  confluenceParentId: "12345",
};
const staticLoader = new StaticSettingsLoader(staticSettings);
const loadedSettings = staticLoader.loadPartial();

EnvironmentVariableSettingsLoader

Purpose: Load settings from environment variables.

Settings source: Environment variables.

Example:

Set the environment variables:

export CONFLUENCE_BASE_URL=https://example.com
export CONFLUENCE_PARENT_ID=12345

Load settings from environment variables:

const envLoader = new EnvironmentVariableSettingsLoader();
const envSettings = envLoader.loadPartial();

ConfigFileSettingsLoader

Purpose: Load settings from a JSON configuration file.

Settings source: User-specified JSON configuration file.

Example:

Create a JSON configuration file (.mermaid-confluence.json):

{
"confluenceBaseUrl": "https://example.com",
"confluenceParentId": "12345"
}

Load settings from the configuration file:

const configFileLoader = new ConfigFileSettingsLoader();
const configFileSettings = configFileLoader.loadPartial();

CommandLineArgumentSettingsLoader

Purpose: Load settings from command line arguments.

Settings source: Command line arguments.

Example:

Pass settings as command line arguments:

node index.js --baseUrl https://example.com --parentId 12345

Load settings from command line arguments:

const cmdLoader = new CommandLineArgumentSettingsLoader();
const cmdSettings = cmdLoader.loadPartial();

AutoSettingsLoader

Purpose: Automatically load and merge settings from multiple loaders.

Settings source: Multiple settings loaders.

Example:

Create an AutoSettingsLoader with custom loaders:

const loaders = [
  new ConfigFileSettingsLoader(),
  new EnvironmentVariableSettingsLoader(),
  new CommandLineArgumentSettingsLoader(),
  new DefaultSettingsLoader()
];

const autoLoader = new AutoSettingsLoader(loaders);
const autoSettings = autoLoader.load();
```

🚀 Mentions Support: It's Time to Have Fun with Mentions! 🎉

Hello there, fellow adventurer! Are you ready to embark on a thrilling journey to bring your Markdown Confluence skills to the next level? Do you want to engage your teammates and colleagues in a fun and interactive way? Say no more, as you've just arrived at the perfect destination! 🌟

Introducing Mentions Support in Markdown-Confluence! A feature that allows you to mention your teammates with flair and pizzazz. It's super easy and fun to use. Let's get started!

🎩 The Magic Mention Formula

To conjure up a mention, you just need to type the following magical incantation:

[[mentions:{userid}|@{Users Name}]]

This magical spell transforms into a marvelous Atlassian Document Format Mention node. You can learn more about the enchanting world of nodes here.

🔍 Seeking the User ID Treasure

But wait! To complete the spell, you'll need the mystical User ID. Fear not, for we shall guide you on your quest!

Set sail to the land of Teams 🏴‍☠️
Unleash the power of the Search 🔍
Click on the desired user to reveal their secret URL 🗝️

For example, if the search URL is:

https://markdown-confluence.atlassian.net/wiki/people/search

And you discover the user's URL to be:

https://markdown-confluence.atlassian.net/wiki/people/557058:aea5688c-52b9-4d15-aabe-96def1abc413

Eureka! You've found the hidden treasure: the User ID! In this case:

557058:aea5688c-52b9-4d15-aabe-96def1abc413

🌈 Making Mention Magic Happen

Now that you've obtained the User ID, you can cast the magical mention spell!

For instance, if you want to mention Captain Confluence with their User ID, you'd simply type:

[[mentions:557058:aea5688c-52b9-4d15-aabe-96def1abc413|@Captain Confluence]]

And there you have it, brave adventurer! You've mastered the art of Mentions Support in Markdown-Confluence. Spread the joy and summon your teammates in a fun and captivating way, making your collaboration experience more delightful than ever! 🎊🎉

Markdown-Confluence: Unleashing the Ninja Power of Raw Atlassian Document Format Blocks 🥷

Greetings, honorable Markdown-Confluence user! Are you ready to unleash the ninja power of raw Atlassian Document Format (ADF) blocks in your Markdown? Behold, the secret technique to render ADF elements in your Markdown-Confluence documents! 🐉

The Secret Art of Raw ADF Blocks

The ancient ninja art of raw ADF blocks allows you to embed ADF content directly into your Markdown document using a special code block. To master this technique, you must first learn the sacred format for raw blocks:

```adf
{"type":"yourADFType","attrs":{...},"content":[...]}
```

The path to enlightenment begins with the following example, young grasshopper:

```adf
{"type":"decisionList","attrs":{"localId":"39becc7a-48c3-4e2d-a6bc-35648d6689a2"},"content":[{"type":"decisionItem","attrs":{"state":"DECIDED","localId":"95268b83-2fc0-4801-9b4f-e5c42cc530e6"},"content":[{"text":"Decision to track","type":"text"}]},{"type":"decisionItem","attrs":{"state":"DECIDED","localId":"564ab974-e6fe-48d2-a144-507f5ec30906"},"content":[{"text":"Testing Decision 2","type":"text"}]}]}
```

This mystical incantation will transform into an ADF node, as described in the ancient scrolls of Atlassian: Atlassian Document Format Structure For the latest information on nodes check out https://atlaskit.atlassian.com/packages/editor/adf-schema. You can use unpkg to view the nodes folder under types and see what attributes you can set on each node type. https://unpkg.com/browse/@atlaskit/adf-schema@25.6.0/dist/types/schema/nodes/. NB. This unpkg link is for a particular version. Make sure you use the latest version for any new updates.

The Forbidden API Technique

To peer into the heart of the atlaskit_doc_format, which stores the ADF content, you must invoke the power of the forbidden API. Gaze upon its hidden knowledge:

https://markdown-confluence.atlassian.net/wiki/rest/api/content/2916353?expand=body.atlas_doc_format

To adapt this technique to your own Confluence domain and page, replace the domain with your Confluence site domain and 2916353 with the page id you wish to reveal the ADF for.

Conclusion

You have now learned the secret ninja art of raw ADF blocks in Markdown-Confluence. Use your newfound power wisely, and remember: with great power comes great responsibility. Now, go forth and create stunning Confluence documents like the ninja you are! 🥷📜💥

Markdown-Confluence Development Guide 🚀

Welcome to the development documentation for the markdown-confluence project! Let's dive into the development process for this fantastic TypeScript project that uses tsc and esbuild for building and packaging.

🛠️ Development Scripts

Here's a detailed overview of the essential scripts that keep our project flowing:

1. dev-obsidian

npm run dev --workspace=@markdown-confluence/lib & npm run dev --workspace=@markdown-confluence/mermaid-electron-renderer & npm run dev --workspace=obsidian-confluence

dev-obsidian is used for local development of the Obsidian plugin. This script simultaneously watches and builds code for the lib, mermaid-electron-renderer, and obsidian-confluence workspaces.

2. build

npm run build -ws --if-present

build is used to build all packages within the workspace. It's essential to run this command whenever you add a new type or modify an exported type across the package boundary to ensure everything is updated accordingly.

3. fmt

npm run fmt -ws --if-present

fmt is a convenient script for formatting all the code in the workspace using Prettier. This command helps maintain code consistency and readability throughout the project.

4. test

npm test -ws --if-present

test is used to run all the tests within the workspace. It helps ensure that new changes don't introduce unexpected issues or break existing functionality.

⚠️ Note: If you add a new type or modify an exported type across the package boundary, make sure to run npm run build.

📘 Obsidian Development

To work on Obsidian development, follow these steps:

Run npm run dev-obsidian. This command builds and watches code, pushing it into the dev-vault part of the repo.
Make sure you've set the appropriate settings, as they're excluded from the repo.
Use the dev-vault in Obsidian to test out the plugin. The hot-reload plugin is installed to automatically reload the plugin right after you save the code.
Sometimes Obsidian might act up, and you'll need to restart it.
Most importantly, have fun! 🎉

🏗️ Building and Testing the CLI

To build and test the CLI for the markdown-confluence project, follow these steps:

1. Build the Project

Before you can test the CLI, you need to build the entire project. Run the following command:

npm run build

This command builds all the packages within the workspace, including the CLI package.

2. Test the CLI

After building the project, you can test the CLI using the output from the dist folder within the cli package. Run the following command:

node ./packages/cli/dist/index.js [options]

Replace [options] with the appropriate options and commands for the markdown-confluence CLI.

See CLI Usage for a list of options.

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.4.0 (2023-05-12)

Features

Handle 404 when pageId included in YAML. Set to not publish and remove bad pageId (33dde01)

5.3.0 (2023-05-11)

Features

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

Markdown Confluence Tools

5.4.0 (2023-05-12)

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)