mark

Mark is a tool designed to sync Markdown files from a Git repository to Atlassian Confluence pages. It automates the process of creating pages, uploading attachments, translating Markdown to HTML, and updating Confluence via the REST API. This allows you to manage documentation in Git without manually using the Confluence editor.

To use extended features like YAML front matter, you must explicitly enable them using the --features flag, as specifying this flag replaces the default feature set.

mark --features=mermaid --features=mention --features=frontmatter

The GitHub Alerts transformer allows Mark to convert GitHub-style alert syntax into Confluence structured macros. It identifies specific blockquote patterns and transforms them into the appropriate Confluence macro type while preserving all nested Markdown formatting.

> [!NOTE]
> This is a note alert with **markdown** formatting.

Features

• GitHub Compatibility: Full support for GitHub's alert syntax.
• Markdown Preservation: All markdown formatting within alerts is preserved.
• Fallback Support: Regular blockquotes without alert syntax (e.g., > text) remain unchanged and are not converted to macros.
• User-Friendly Labels: Automatically adds readable labels (Note, Tip, Warning, etc.) to the alert content.

Backward Compatibility

• Legacy syntax such as info:, tip:, and warning: continues to work.
• Regular blockquotes remain unchanged.

You can define placeholders within your markdown using the following syntax. These are useful for marking areas that require specific content or dynamic insertion.

<!-- ac:placeholder -->
Placeholder
<!-- ac:placeholder end -->

Mark can be integrated into CI/CD systems (like Snake CI, GitHub Actions, or Bitbucket Pipelines) to automatically sync documentation when changes are merged to a main branch.

When running in CI, it is recommended to use the --ci flag, which prevents the tool from failing if files are not found. You can use environment variables for credentials to keep them secure.

stages:
  - sync

Sync documentation:
  stage: sync
  only:
    branches:
      - main
  image: kovetskiy/mark
  commands:
    - for file in $(find -type f -name '*.md'); do
        echo "> Sync $file";
        mark -u $MARK_USER -p $MARK_PASS -b $MARK_URL -f $file || exit 1;
        echo;
      done

Mark supports GitHub Flavored Markdown (GFM) task lists. These are automatically converted to Confluence ac:task-list elements.

Syntax:

- [x] Finished task
- [ ] Unfinished task

Note on Mixed Lists: If a list contains both tasks and regular list items, Mark falls back to a standard HTML list with textual markers (e.g., [x] or [ ]) to ensure the Confluence storage format remains valid.

Mark can transform code blocks into images for Confluence.

Mermaid (Built-in)

Simply use a mermaid code block. Mark renders it as a PNG and attaches it.

graph TD;
A-->B;

D2 (Requires --features="d2")

X -> Y

PlantUML (Requires --features="plantuml")

Note: This requires the 'PlantUML for Confluence Macro' to be installed in your Confluence instance.

@startuml
Alice -> Bob: Authentication Request
@enduml

You can install the mark CLI tool using several methods:

Homebrew

brew tap kovetskiy/mark
brew install mark

Go Install

go install github.com/kovetskiy/mark/v16/cmd/mark@latest

Docker

Run the tool directly using a Docker container:

docker run --rm -i kovetskiy/mark:latest mark <params>

Manual Compilation (via Docker Compose)

If you are enhancing the tool, you can build and install it using the provided docker-compose setup:

# Create the binary
docker-compose run markbuilder
# "install" the binary
cp mark /usr/local/bin