English | 日本語

md2bl

A CLI tool and library to convert Markdown to Backlog notation.

Converts Markdown into a format that can be pasted directly into issues, Wikis, and PRs in Backlog projects that use Backlog notation. Supports stdin/stdout piping, making it easy to integrate into shell scripts and other tools. Also usable as a library in Node.js/TypeScript projects.

Installation

Requires Node.js 18 or later.

npm install -g md2bl

Usage

Programmatic Usage

You can also use md2bl as a library in your Node.js/TypeScript project:

npm install md2bl

import { convert } from 'md2bl';

const backlog = convert('# Hello **world**');
console.log(backlog);
// => * Hello ''world''

Convert a file

md2bl input.md

Read from stdin (pipe)

cat input.md | md2bl
echo "# Hello" | md2bl

Write to a file

md2bl input.md > output.txt

Conversion Example

Input (Markdown):

[toc]

# Heading 1

First paragraph. You can use **bold** and *italic* text.

Second paragraph (blank lines between paragraphs are preserved).

- List item 1
  - Nested item
- List item 2

1. Ordered item 1
2. Ordered item 2

- First paragraph

  Second paragraph (loose list item)

- Item with code:

  ```java
  System.out.println("hello");
  ```

[Link](https://example.com)

| Col A | Col B |
|-------|-------|
| Val 1 | Val 2 |

Output (Backlog notation):

#contents
* Heading 1
First paragraph. You can use ''bold'' and '''italic''' text.

Second paragraph (blank lines between paragraphs are preserved).
- List item 1
-- Nested item
- List item 2

+ Ordered item 1
+ Ordered item 2
- First paragraph&br;Second paragraph (loose list item)
- Item with code:
{code:java}
System.out.println("hello");
{/code}
[[Link:https://example.com]]
| Col A | Col B |h
| Val 1 | Val 2 |

Conversion Rules

| Markdown | Backlog Notation | |----------|-----------------| | # Heading 1 | * Heading 1 | | ## Heading 2 | ** Heading 2 | | ### Heading 3 | *** Heading 3 | | **bold** | ''bold'' | | *italic* | '''italic''' | | ~~strikethrough~~ | %%strikethrough%% | | `inline code` | {code}inline code{/code} | | ```lang ... ``` | {code} ... {/code} (java/cs → {code:lang}) | | [text](URL) (text≠URL) | [[text:URL]] | | [URL](URL) / bare URL | URL output as-is | | > blockquote | > blockquote | | --- | ---- | | - item | - item | | - nested (2 levels) | -- nested | | 1. item | + item | | 1. nested (2 levels) | ++ nested | | - [ ] text / - [x] text | - [ ] text / - [x] text | | 1. [ ] text / 1. [x] text | + [ ] text / + [x] text | | Loose list item (multiple paragraphs) | Joined with &br; | | Code block in list item (single line) | {code}...{/code} inline with &br; | | Code block in list item (multi-line) | {code} block without bullet | | Blockquote / HR / table in list item | Output without bullet | | ![alt](url) | #image(url) | | [toc] | #contents | | Table | Header row ends with h suffix | | YAML front matter | Output as-is |

Note: Blank lines between blocks are removed by default. Only blank lines between paragraph → paragraph and list → list are preserved.

Note: Backlog notation only supports syntax highlighting for java and cs (C#). Other languages fall back to {code} without highlighting.

Unsupported Elements

The following elements are skipped with a warning output to stderr.

• Raw HTML
• Footnotes

Development

npm run dev          # Run directly with tsx (no build required)
npm test             # Run tests with vitest
npm run build        # Build TypeScript

Tech Stack

• TypeScript / Node.js (ESM)
• unified / remark — Markdown AST parsing
• remark-gfm — GitHub Flavored Markdown support
• remark-frontmatter — YAML front matter support
• vitest — Testing

License

MIT