<!-- BusyBot node reference — https://busybot.net/tools/markdown/ -->

> Node: Markdown (`markdown`) · Action · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Markdown

> Convert between Markdown and HTML

## Overview

The Markdown tool converts between Markdown and HTML in both directions. HTML→Markdown uses node-html-markdown with options for bullet markers, code fences, emphasis delimiters, text replacement patterns, and more. Markdown→HTML uses showdown with 25+ options including emoji support, tables, strikethrough, task lists, and GitHub-compatible features.

**Category:** Core Nodes  
**Tool Name:** `markdown`  
**Version:** 1

**Appearance:** Icon: `lucide-FileText` | Color: `#000000`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

The two Options collections are mutually exclusive — only the one matching the selected Mode is shown.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mode | `options` | No | `htmlToMarkdown` | Conversion direction. |
| | | | | Options: `markdownToHtml` (convert data from Markdown to HTML), `htmlToMarkdown` (convert data from HTML to Markdown) |
| HTML | `string` | Yes | — | The HTML to convert to Markdown. Supports expressions like {{ $json.htmlContent }}. _(shown when Mode is `htmlToMarkdown`)_ |
| Markdown | `string` | Yes | — | The Markdown to convert to HTML. Supports expressions like {{ $json.docContent }}. _(shown when Mode is `markdownToHtml`)_ |
| Destination Key | `string` | Yes | `data` | The field to put the output in. Supports dot-notation for nested fields. |
| Options (`options`) | `collection` | No | `{}` | HTML→Markdown conversion settings. _(shown when Mode is `htmlToMarkdown`)_ |
| — Bullet Marker | `string` | No | `*` | Character used for unordered list bullets. |
| — Code Block Fence | `string` | No | `` ``` `` | Fence characters used around code blocks. |
| — Emphasis Delimiter | `string` | No | `_` | Delimiter used for emphasis (italic) text. |
| — Global Escape Pattern | `fixedCollection` | No | `{}` | A find/replace pair applied across the whole converted document. |
| — — Pattern | `string` | No | — | Regular expression to match. |
| — — Replacement | `string` | No | — | Text to replace each match with. |
| — Ignored Elements | `string` | No | — | Comma-separated HTML elements to ignore. |
| — Keep Images With Data | `boolean` | No | `false` | Preserve images whose source is a `data:` URL. |
| — Line Start Escape Pattern | `fixedCollection` | No | `{}` | A find/replace pair applied only at the start of each line. |
| — — Pattern | `string` | No | — | Regular expression to match. |
| — — Replacement | `string` | No | — | Text to replace each match with. |
| — Max Consecutive New Lines | `number` | No | `3` | Maximum number of blank lines kept in a row. |
| — Place URLs At The Bottom | `boolean` | No | `false` | Use reference-style links and collect the URLs at the end of the document. |
| — Strong Delimiter | `string` | No | `**` | Delimiter used for strong (bold) text. |
| — Style For Code Block | `options` | No | `fence` | How code blocks are written in the Markdown output. |
| | | | | Options: `fence`, `indented` |
| — Text Replacement Pattern | `fixedCollection` | No | `[]` | Find/replace pairs applied to the converted text. Accepts multiple entries. |
| — — Pattern | `string` | No | — | Regular expression to match. |
| — — Replacement | `string` | No | — | Text to replace each match with. |
| — Treat As Blocks | `string` | No | — | Comma-separated elements to treat as blocks. |
| Options (`options`) | `collection` | No | `{}` | Markdown→HTML conversion settings. _(shown when Mode is `markdownToHtml`)_ |
| — Add Blank To Links | `boolean` | No | `false` | Open generated links in a new window. |
| — Automatic Linking to URLs | `boolean` | No | `false` | Turn bare URLs in the text into links. |
| — Backslash Escapes HTML Tags | `boolean` | No | `false` | Allow a backslash to escape an HTML tag so it renders literally. |
| — Complete HTML Document | `boolean` | No | `false` | Emit a full HTML document rather than a fragment. |
| — Customized Header ID | `boolean` | No | `false` | Allow a heading to declare its own id. |
| — Emoji Support | `boolean` | No | `false` | Convert emoji shortcodes into emoji characters. |
| — Encode Emails | `boolean` | No | `true` | Obfuscate email addresses to make scraping harder. |
| — Exclude Trailing Punctuation From URLs | `boolean` | No | `false` | Leave trailing punctuation outside an auto-generated link. |
| — GitHub Code Blocks | `boolean` | No | `true` | Support GitHub-flavored fenced code blocks. |
| — GitHub Compatible Header IDs | `boolean` | No | `false` | Generate heading ids the way GitHub does. |
| — GitHub Mention Link | `string` | No | `https://github.com/{u}` | Link template used for mentions, where `{u}` is the user name. |
| — GitHub Mentions | `boolean` | No | `false` | Turn `@name` into a mention link. |
| — GitHub Task Lists | `boolean` | No | `false` | Render `- [ ]` and `- [x]` as checkboxes. |
| — Header Level Start | `number` | No | `1` | Heading level that a single `#` maps to. |
| — Mandatory Space Before Header | `boolean` | No | `false` | Require a space between `#` and the heading text. |
| — Middle Word Asterisks | `boolean` | No | `false` | Treat asterisks inside a word as literal characters. |
| — Middle Word Underscores | `boolean` | No | `false` | Treat underscores inside a word as literal characters. |
| — No Header ID | `boolean` | No | `false` | Do not add ids to headings. |
| — Parse Image Dimensions | `boolean` | No | `false` | Read width/height hints in image syntax. |
| — Prefix Header ID | `string` | No | `section` | Prefix added to generated heading ids. |
| — Raw Header ID | `boolean` | No | `false` | Use the raw heading text as the id without cleaning it up. |
| — Raw Prefix Header ID | `boolean` | No | `false` | Use the heading id prefix exactly as written. |
| — Simple Line Breaks | `boolean` | No | `false` | Treat a single newline as a line break. |
| — Smart Indentation Fix | `boolean` | No | `false` | Correct indentation that would otherwise break nested blocks. |
| — Spaces Indented Sublists | `boolean` | No | `false` | Do not require four-space indentation for sublists. |
| — Split Adjacent Blockquotes | `boolean` | No | `false` | Keep neighbouring blockquotes as separate blocks. |
| — Strikethrough | `boolean` | No | `false` | Support `~~text~~` strikethrough syntax. |
| — Tables Header ID | `boolean` | No | `false` | Add ids to table header cells. |
| — Tables Support | `boolean` | No | `false` | Support Markdown table syntax. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The converted text is written to the field named by **Destination Key** (`data` by default); the rest of the input item JSON passes through unchanged, and binary data is forwarded.

Destination Key accepts dot-notation, so `post.markdown` creates the nested objects it needs and writes the result at the end of the path.

The source content comes from the **HTML** or **Markdown** parameter, not from a fixed field on the item — point it at the item with an expression such as `{{ $json.htmlContent }}`.

Reference the result downstream by expression, e.g. `{{ $json.data }}`.

## Usage Examples

- Convert Markdown README to HTML
- Convert HTML email to Markdown for processing

## Example Configuration

Convert HTML to Markdown:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "htmlToMarkdown",
    "html": "<h1>Title</h1><p>This is a paragraph.</p>",
    "destinationKey": "markdownOutput"
  }
}
```

Convert HTML to Markdown with formatting options:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "htmlToMarkdown",
    "html": "<h1>Title</h1><ul><li>Item 1</li><li>Item 2</li></ul>",
    "destinationKey": "markdownOutput",
    "options": {
      "bulletMarker": "-",
      "strongDelimiter": "**",
      "maxConsecutiveNewlines": 2,
      "keepDataImages": true
    }
  }
}
```

Convert HTML to Markdown with a text replacement:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "htmlToMarkdown",
    "html": "<p>Hello world</p>",
    "destinationKey": "result",
    "options": {
      "textReplace": {
        "values": [
          {
            "pattern": "world",
            "replacement": "universe"
          }
        ]
      }
    }
  }
}
```

Convert HTML to Markdown with a global escape:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "htmlToMarkdown",
    "html": "<p>Some [bracketed] text</p>",
    "destinationKey": "result",
    "options": {
      "globalEscape": {
        "value": {
          "pattern": "\\[",
          "replacement": "\\\\["
        }
      }
    }
  }
}
```

Convert HTML to Markdown with a line-start escape:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "htmlToMarkdown",
    "html": "<p>## Not a heading</p>",
    "destinationKey": "result",
    "options": {
      "lineStartEscape": {
        "value": {
          "pattern": "^##",
          "replacement": "\\##"
        }
      }
    }
  }
}
```

Convert Markdown to HTML:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "markdownToHtml",
    "markdown": "# Title\n\nThis is a **bold** paragraph.",
    "destinationKey": "htmlOutput"
  }
}
```

Convert Markdown to HTML with GitHub features:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "markdownToHtml",
    "markdown": "# Project\n\n- [x] Task 1\n- [ ] Task 2",
    "destinationKey": "htmlOutput",
    "options": {
      "ghCodeBlocks": true,
      "tasklists": true,
      "tables": true,
      "strikethrough": true,
      "emoji": true
    }
  }
}
```

Produce a complete HTML document:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "markdownToHtml",
    "markdown": "# Welcome\n\nThis is my website.",
    "destinationKey": "fullHtml",
    "options": {
      "completeHTMLDocument": true,
      "openLinksInNewWindow": true,
      "headerLevelStart": 2,
      "prefixHeaderId": "section"
    }
  }
}
```

Convert scraped HTML posts to Markdown for storage, writing to a nested field:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "htmlToMarkdown",
    "html": "{{ $json.htmlContent }}",
    "destinationKey": "post.markdown",
    "options": {
      "bulletMarker": "-",
      "codeFence": "~~~",
      "useLinkReferenceDefinitions": false,
      "maxConsecutiveNewlines": 3
    }
  }
}
```

Render documentation with GitHub features:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "markdownToHtml",
    "markdown": "{{ $json.docContent }}",
    "destinationKey": "documentation.html",
    "maxConcurrency": 5,
    "options": {
      "ghCodeBlocks": true,
      "tables": true,
      "tasklists": true,
      "ghMentions": true,
      "ghMentionsLink": "https://github.com/{u}",
      "emoji": true
    }
  }
}
```

Generate email-friendly HTML:

```json
{
  "type": "markdown",
  "parameters": {
    "mode": "markdownToHtml",
    "markdown": "{{ $json.emailTemplate }}",
    "destinationKey": "email.body",
    "options": {
      "simpleLineBreaks": true,
      "encodeEmails": true,
      "noHeaderId": true,
      "openLinksInNewWindow": true
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Converts between Markdown and HTML using showdown (MD→HTML) and node-html-markdown (HTML→MD).

### Behavior notes

- **The content is a parameter, not a fixed field.** Put an expression in HTML or Markdown — `{{ $json.htmlContent }}` — to convert whatever the upstream item carries. Leaving it as literal text converts that same text for every item.
- **Destination Key is fixed for the node.** It is read once per run, so every item writes its result to the same path.
- **Switching Mode swaps the whole Options set.** Settings configured for one direction are not carried over to the other; each direction has its own collection.
- **Use Ignored Elements to drop boilerplate.** Passing `script, style, nav, footer` keeps navigation chrome out of the Markdown when converting scraped pages.
- **Tables and task lists are off by default** when converting Markdown to HTML — turn on Tables Support and GitHub Task Lists if your source relies on them.