Mark

Mark — a tool for syncing your markdown documentation with Atlassian Confluence pages.

This is very useful if you store documentation to your software in a Git repository and don't want to do an extra job of updating Confluence page using a tinymce wysiwyg enterprise core editor which always breaks everything.

Mark does the same but in a different way. Mark reads your markdown file, creates a Confluence page if it's not found by its name, uploads attachments, translates Markdown into HTML and updates the contents of the page via REST API. It's like you don't even need to create sections/pages in your Confluence anymore, just use them in your Markdown documentation.

Mark uses an extended file format, which, still being valid markdown, contains several HTML-ish metadata headers, which can be used to locate page inside Confluence instance and update it accordingly.

File in the extended format should follow the specification:

<!-- Space: <space key> -->
<!-- Parent: <parent 1> -->
<!-- Parent: <parent 2> -->
<!-- Title: <title> -->
<!-- Attachment: <local path> -->
<!-- Label: <label 1> -->
<!-- Label: <label 2> -->
<!-- Image-Align: <left|center|right> -->

<page contents>

There can be any number of Parent headers, if Mark can't find specified parent by title, Mark creates it.

Also, optional following headers are supported:

<!-- Layout: (article|plain) -->

(default) article: content will be put in narrow column for ease of reading;
plain: content will fill all page;

<!-- Type: (page|blogpost) -->

(default) page: normal Confluence page - defaults to this if omitted
blogpost: Blog post in Space. Cannot have Parent(s)

<!-- Content-Appearance: (full-width|fixed) -->

(default) full-width: content will fill the full page width
fixed: content will be rendered in a fixed narrow view

<!-- Sidebar: <h2>Test</h2> -->

Setting the sidebar creates a column on the right side. You're able to add any valid HTML content. Adding this property sets the layout to article.

<!-- Emoji: 🚀 -->

You can set a page emoji icon by specifying the icon in the headers.

<!-- Image-Align: center -->

You can set the alignment for all images in the page. Common values are left, center, and right. Can also be set globally via the --image-align CLI option (per-page header takes precedence).

Note: Images with width >= 760px automatically use center instead of the configured alignment, as Confluence requires this for wide images.

Mark supports Go templates, which can be included into article by using path to the template relative to current working dir, e.g.:

<!-- Include: <path> -->

If the template cannot be found relative to the current directory, a fallback directory can be defined via --include-path. This way it is possible to have global include files while local ones will still take precedence.

Optionally the delimiters can be defined:

<!-- Include: <path>
     Delims: "<<", ">>"
     -->

Or they can be switched off to disable processing:

<!-- Include: <path>
     Delims: none
     -->

Note: Switching delimiters off really simply changes them to ASCII characters "\x00" and "\x01" which, usually should not occure in a template.

Templates can accept configuration data in YAML format which immediately follows the Include and Delims tag, if present:

<!-- Include: <path>
     <yaml-data> -->

Mark also supports attachments. The standard way involves declaring an Attachment along with the other items in the header, then have any links with the same path:

<!-- Attachment: <path-to-image> -->

<beginning of page content>

An attached link is [here](<path-to-image>)

NOTE: Be careful with Attachment! If your path string is a subset of another longer string or referenced in text, you may get undesired behavior.

Mark also supports macro definitions, which are defined as regexps which will be replaced with specified template:

<!-- Macro: <regexp>
     Template: <path>
     <yaml-data> -->

NOTE: Make sure to define your macros after your metadata (Title/Space), mark will stop processing metadata if it hits a Macro.

Capture groups can be defined in the macro's <regexp> which can be later referenced in the <yaml-data> using ${<number>} syntax, where <number> is number of a capture group in regexp (${0} is used for entire regexp match), for example:

  <!-- Macro: MYJIRA-\d+
       Template: ac:jira:ticket
       Ticket: ${0} -->

Macros can also use inline templates. Inline templates are templates where the template content is described in the <yaml-data>. The Template value starts with a #, followed by the key used in the <yaml-data>. The key's value must be a string which defines the template's content.

  <!-- Macro: <tblbox\s+(.*?)\s*>
       Template: #inline
       title: ${1}
       inline: |
           <table>
           <thead><tr><th>{{ .title }}</th></tr></thead>
           <tbody><tr><td>
        -->
  <!-- Macro: </tblbox>
       Template: #also_inline
       also_inline: |
           </td></tr></tbody></table>
        -->
  <tblbox with a title>
  and some
  content
  </tblbox>

Automatic Page Title

If you don't want to specify the page title in the metadata of each file, mark provides two ways to set it automatically.

From the first H1 heading

You can use the --title-from-h1 flag to extract the page title from the first H1 heading in the markdown file. If no H1 heading is found, the title must be set in the page metadata.

From the filename

You can use the --title-from-filename flag to use the filename (without the extension) as the page title. mark will automatically convert the filename to a more readable title by:

Replacing underscores (_) and dashes (-) with spaces.
Applying title case to the filename.

For example, a file named my_awesome-page.md will have the title "My Awesome Page".

These two options are mutually exclusive. If both flags are provided, mark will produce an error.

Customizing the page layout

If you set the Layout to plain, the page layout can be customized using HTML comments inside the markdown:

<!-- Layout: plain -->
<!-- ac:layout -->

<!-- ac:layout-section type:three_with_sidebars -->
<!-- ac:layout-cell -->
More Content
<!-- ac:layout-cell end -->
<!-- ac:layout-cell -->
More Content
<!-- ac:layout-cell end -->
<!-- ac:layout-cell -->
Even More Content
<!-- ac:layout-cell end -->
<!-- ac:layout-section end -->

<!-- ac:layout-section type:single -->
<!-- ac:layout-cell -->
Still More Content
<!-- ac:layout-cell end -->
<!-- ac:layout-section end -->

<!-- ac:layout end -->

Please be aware that mark does not validate the layout, so it's your responsibility to create a valid layout.

Placeholders

You can use this to define placeholders:

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

Code Blocks

```bash
...
some long bash code block
...
```

| Parameter | Default | | ------------------------------ | ------- | | collapse | false | | title | none | | linenumbers | false | | 1 (any number for firstline) | 1 |

Example:

bash collapse If you have long code blocks, you can make them collapsible.
bash collapse title Some long long bash function And you can also add a title.
bash linenumbers collapse title Some long long bash function And linenumbers.
bash 1 collapse title Some long long bash function Or directly give a number as firstline number.
bash 1 collapse midnight title Some long long bash function And even themes.
- 1 collapse midnight title Some long long code Please note that, if you want to have a code block without a language use - as the first character, if you want to have the other goodies.

More details at Confluence Code Block Macro doc.

Block Quotes

Block Quotes are converted to Confluence Info/Warn/Note box when the following conditions are met

The BlockQuote is on the root level of the document (not nested)
The first line of the BlockQuote contains one of the following patterns Info/Warn/Note or Github MD Alerts style [!NOTE]/[!TIP]/[!IMPORTANT]/[!WARNING]/[!CAUTION]

| Github Alerts | Confluence | | --- | --- | | Tip (green lightbulb) | Tip (green checkmark in circle) | | Note (blue I in circle) | Info (blue I in circle) | | Important (purple exclamation mark in speech bubble) | Info (blue I in circle) | | Warning (yellow exclamation mark in triangle) | Note (yellow exclamation mark in triangle) | | Caution (red exclamation mark in hexagon) | Warning (red exclamation mark in hexagon) |

In any other case the default behaviour will be resumed and html <blockquote> tag will be used

Template & Macros

By default, mark provides several built-in templates and macros:

template ac:status to include badge-like text, which accepts following parameters:
- Title: text to display in the badge
- Color: color to use as background/border for badge
  - Grey
  - Red
  - Yellow
  - Green
  - Blue
- Subtle: specify to fill badge with background or not
  - t

Mark

Install / Use

README

Mark

Automatic Page Title

From the first H1 heading

From the filename

Customizing the page layout

Placeholders

Code Blocks

Block Quotes

Template & Macros