Command-line tool

Meziantou.Framework.AtlassianDataFormat.Tool converts ADF documents to Markdown without writing code: use it in scripts, for instance to export the description of a Jira issue.

The command reference lists every option of the tool.

Install the tool

Install it as a global tool:

dotnet tool install --global Meziantou.Framework.AtlassianDataFormat.Tool

Convert a file

--input is the ADF document, and --output the Markdown file to write:

Meziantou.Framework.AtlassianDataFormat.Tool --input issue.json --output issue.md

With this document:

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [ { "type": "text", "text": "Steps to reproduce" } ]
    },
    {
      "type": "orderedList",
      "content": [
        {
          "type": "listItem",
          "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Open the " }, { "type": "text", "text": "settings", "marks": [ { "type": "strong" } ] } ] } ]
        },
        {
          "type": "listItem",
          "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Click " }, { "type": "text", "text": "Save", "marks": [ { "type": "code" } ] } ] } ]
        }
      ]
    },
    {
      "type": "panel",
      "attrs": { "panelType": "warning" },
      "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "The application stops responding." } ] } ]
    },
    {
      "type": "expand",
      "attrs": { "title": "Environment" },
      "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Version 2.1 on Windows 11" } ] } ]
    }
  ]
}

the tool writes:

## Steps to reproduce

1. Open the **settings**
2. Click `Save`

> ⚠️ The application stops responding.

> **Environment**
>
> Version 2.1 on Windows 11

• Without --output, the Markdown is written to the standard output.
• The folder of the output file is created if needed, and the file is written in UTF-8 without a byte order mark.
• The Markdown ends with a line terminator. An empty input gives an empty output.

Read the standard input

Without --input, the tool reads the document from the standard input. Pipe the description of a Jira issue to it:

curl -s -u "$JIRA_USER:$JIRA_TOKEN" "https://example.atlassian.net/rest/api/3/issue/ABC-1" | jq .fields.description | Meziantou.Framework.AtlassianDataFormat.Tool

Options

Every option of the conversion is a command-line option with the same default. The same document, converted with GitHub alerts and HTML collapsible sections:

Meziantou.Framework.AtlassianDataFormat.Tool --input issue.json --panel-style GitHubAlert --expand-style HtmlDetails

## Steps to reproduce

1. Open the **settings**
2. Click `Save`

> [!WARNING]
> The application stops responding.

<details>
<summary>Environment</summary>

Version 2.1 on Windows 11

</details>

--help lists the options with their defaults. The media and mention resolvers have no command-line option: media stored by Atlassian is written as its alternative text, and a mention without a display name as its identifier.

Errors

The tool exits with code 1, and writes the reason to the standard error, when the input file does not exist or the input is not an ADF document. With --unknown-node-handling Throw, an unknown node is such an error.