Markdown to Notion: Convert Markdown and GitHub Flavoured Markdown to Notion API Blocks and RichText ππ
See the codeConvert Markdown and GitHub Flavoured Markdown to Notion API Blocks and RichText.
Martian is a Markdown parser to convert any Markdown content to Notion API block or RichText objects. It uses unified to create a Markdown AST, then converts the AST into Notion objects.
Designed to make using the Notion SDK and API easier. Notion API version 1.0.
enableEmojiCallouts)The package exports two functions, which you can import like this:
// JS
const {markdownToBlocks, markdownToRichText} = require('@tryfabric/martian');
// TS
import {markdownToBlocks, markdownToRichText} from '@tryfabric/martian';
Here are couple of examples with both of them:
markdownToRichText(`**Hello _world_**`);
[
{
"type": "text",
"annotations": {
"bold": true,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "Hello "
}
},
{
"type": "text",
"annotations": {
"bold": true,
"strikethrough": false,
"underline": false,
"italic": true,
"code": false,
"color": "default"
},
"text": {
"content": "world"
}
}
]
markdownToBlocks(`
hello _world_
***
## heading2
* [x] todo
> π **Note:** Important _information_
> Some other blockquote
`);
[
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "hello "
}
},
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": true,
"code": false,
"color": "default"
},
"text": {
"content": "world"
}
}
]
}
},
{
"object": "block",
"type": "divider",
"divider": {}
},
{
"object": "block",
"type": "heading_2",
"heading_2": {
"rich_text": [
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "heading2"
}
}
]
}
},
{
"object": "block",
"type": "to_do",
"to_do": {
"rich_text": [
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "todo"
}
}
],
"checked": true
}
},
{
"type": "callout",
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Note:"
},
"annotations": {
"bold": true,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
}
},
{
"type": "text",
"text": {
"content": " Important "
}
},
{
"type": "text",
"text": {
"content": "information"
},
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": true,
"code": false,
"color": "default"
}
}
],
"icon": {
"type": "emoji",
"emoji": "π"
},
"color": "blue_background"
}
},
{
"type": "quote",
"quote": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Some other blockquote"
},
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
}
}
]
}
}
]
Martian supports three types of blockquotes:
> This is a regular blockquote
> It can span multiple lines
> [!NOTE]
> Important information that users should know
> [!WARNING]
> Critical information that needs attention
> π **Note:** This is a callout with a blue background
> It supports all markdown formatting and can span multiple lines
> β **Warning:** This is a callout with a red background
> Perfect for important warnings
GFM alerts are automatically converted to Notion callouts with appropriate icons and colors:
By default, emoji-style callouts are disabled. You can enable them using the enableEmojiCallouts option:
const options = {
enableEmojiCallouts: true,
};
When enabled, callouts are detected when a blockquote starts with an emoji. The emoji determines the callout's background color. The current supported color mappings are:
All other emojis will have a default background color. The supported emoji color mappings can be expanded easily if needed.
If a blockquote doesn't match either GFM alert syntax or emoji-style callout syntax (when enabled), it will be rendered as a Notion quote block.
Standard blockquote:
markdownToBlocks('> A regular blockquote');
[
{
"object": "block",
"type": "quote",
"quote": {
"rich_text": [
{
"type": "text",
"text": {
"content": "A regular blockquote"
}
}
]
}
}
]
GFM alert:
markdownToBlocks('> [!NOTE]\n> Important information');
[
{
"object": "block",
"type": "callout",
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Note"
}
}
],
"icon": {
"type": "emoji",
"emoji": "βΉοΈ"
},
"color": "blue_background",
"children": [
{
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Important information"
}
}
]
}
}
]
}
}
]
Emoji-style callout (with enableEmojiCallouts: true):
markdownToBlocks('> π Note: Important information', {
enableEmojiCallouts: true,
});
[
{
"object": "block",
"type": "callout",
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Note: Important information"
}
}
],
"icon": {
"type": "emoji",
"emoji": "π"
},
"color": "blue_background"
}
}
]
Sometimes a Markdown input would result in an output that would be rejected by the Notion API: here are some options to deal with that.
By default, the package will try to resolve these kind of issues by re-distributing the content to multiple blocks: when that's not possible, martian will truncate the output to avoid your request resulting in an error.
If you want to disable this kind of behavior, you can use this option:
const options = {
notionLimits: {
truncate: false,
},
};
markdownToBlocks('input', options);
markdownToRichText('input', options);
You can set a callback for when one of the resulting items would exceed Notion's limits. Please note that this function will be called regardless of whether the final output will be truncated.
const options = {
notionLimits: {
// truncate: true, // by default
onError: (err: Error) => {
// Something has appened!
console.error(err);
},
},
};
markdownToBlocks('input', options);
markdownToRichText('input', options);
If an image as an invalid URL, the Notion API will reject the whole request: martian prevents this issue by converting images with invalid links into text, so that request are successfull and you can fix the links later.
If you want to disable this kind of behavior, you can use this option:
const options = {
strictImageUrls: false,
};
Default behavior:
markdownToBlocks('');
[
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "InvalidURL"
}
}
]
}
}
]
strictImageUrls disabled:
markdownToBlocks('', {
strictImageUrls: false,
});
[
{
"object": "block",
"type": "image",
"image": {
"type": "external",
"external": {
"url": "InvalidURL"
}
}
}
]
By default, if the text provided to markdownToRichText would result in one or more non-inline elements, the package will ignore those and only parse paragraphs.
You can make the package throw an error when a non-inline element is detected by setting the nonInline option to 'throw'.
Default behavior:
markdownToRichText('# Header\nAbc', {
// nonInline: 'ignore', // Default
});
[
{
type: 'text',
annotations: {
bold: false,
strikethrough: false,
underline: false,
italic: false,
code: false,
color: 'default'
},
text: { content: 'Abc', link: undefined }
}
]
Throw an error:
markdownToRichText('# Header\nAbc', {
nonInline: 'throw',
});
Error: Unsupported markdown element: {"type":"heading","depth":1,"children":[{"type":"text","value":"Header","position":{"start":{"line":1,"column":3,
"offset":2},"end":{"line":1,"column":9,"offset":8}}}],"position":{"start":{"line":1,"column":1,"offset":0},"end":{"line":1,"column":9,"offset":8}}}
Built with π by the team behind Fabric.
1,654 followers Β· starred Jul 2025
1,921 followers Β· starred Dec 2022
4,037 followers Β· starred Feb 2026
560 followers Β· starred Oct 2022
Markdown to Notion: Convert Markdown and GitHub Flavoured Markdown to Notion API Blocks and RichText ππ
See the codeConvert Markdown and GitHub Flavoured Markdown to Notion API Blocks and RichText.
Martian is a Markdown parser to convert any Markdown content to Notion API block or RichText objects. It uses unified to create a Markdown AST, then converts the AST into Notion objects.
Designed to make using the Notion SDK and API easier. Notion API version 1.0.
enableEmojiCallouts)The package exports two functions, which you can import like this:
// JS
const {markdownToBlocks, markdownToRichText} = require('@tryfabric/martian');
// TS
import {markdownToBlocks, markdownToRichText} from '@tryfabric/martian';
Here are couple of examples with both of them:
markdownToRichText(`**Hello _world_**`);
[
{
"type": "text",
"annotations": {
"bold": true,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "Hello "
}
},
{
"type": "text",
"annotations": {
"bold": true,
"strikethrough": false,
"underline": false,
"italic": true,
"code": false,
"color": "default"
},
"text": {
"content": "world"
}
}
]
markdownToBlocks(`
hello _world_
***
## heading2
* [x] todo
> π **Note:** Important _information_
> Some other blockquote
`);
[
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "hello "
}
},
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": true,
"code": false,
"color": "default"
},
"text": {
"content": "world"
}
}
]
}
},
{
"object": "block",
"type": "divider",
"divider": {}
},
{
"object": "block",
"type": "heading_2",
"heading_2": {
"rich_text": [
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "heading2"
}
}
]
}
},
{
"object": "block",
"type": "to_do",
"to_do": {
"rich_text": [
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "todo"
}
}
],
"checked": true
}
},
{
"type": "callout",
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Note:"
},
"annotations": {
"bold": true,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
}
},
{
"type": "text",
"text": {
"content": " Important "
}
},
{
"type": "text",
"text": {
"content": "information"
},
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": true,
"code": false,
"color": "default"
}
}
],
"icon": {
"type": "emoji",
"emoji": "π"
},
"color": "blue_background"
}
},
{
"type": "quote",
"quote": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Some other blockquote"
},
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
}
}
]
}
}
]
Martian supports three types of blockquotes:
> This is a regular blockquote
> It can span multiple lines
> [!NOTE]
> Important information that users should know
> [!WARNING]
> Critical information that needs attention
> π **Note:** This is a callout with a blue background
> It supports all markdown formatting and can span multiple lines
> β **Warning:** This is a callout with a red background
> Perfect for important warnings
GFM alerts are automatically converted to Notion callouts with appropriate icons and colors:
By default, emoji-style callouts are disabled. You can enable them using the enableEmojiCallouts option:
const options = {
enableEmojiCallouts: true,
};
When enabled, callouts are detected when a blockquote starts with an emoji. The emoji determines the callout's background color. The current supported color mappings are:
All other emojis will have a default background color. The supported emoji color mappings can be expanded easily if needed.
If a blockquote doesn't match either GFM alert syntax or emoji-style callout syntax (when enabled), it will be rendered as a Notion quote block.
Standard blockquote:
markdownToBlocks('> A regular blockquote');
[
{
"object": "block",
"type": "quote",
"quote": {
"rich_text": [
{
"type": "text",
"text": {
"content": "A regular blockquote"
}
}
]
}
}
]
GFM alert:
markdownToBlocks('> [!NOTE]\n> Important information');
[
{
"object": "block",
"type": "callout",
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Note"
}
}
],
"icon": {
"type": "emoji",
"emoji": "βΉοΈ"
},
"color": "blue_background",
"children": [
{
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Important information"
}
}
]
}
}
]
}
}
]
Emoji-style callout (with enableEmojiCallouts: true):
markdownToBlocks('> π Note: Important information', {
enableEmojiCallouts: true,
});
[
{
"object": "block",
"type": "callout",
"callout": {
"rich_text": [
{
"type": "text",
"text": {
"content": "Note: Important information"
}
}
],
"icon": {
"type": "emoji",
"emoji": "π"
},
"color": "blue_background"
}
}
]
Sometimes a Markdown input would result in an output that would be rejected by the Notion API: here are some options to deal with that.
By default, the package will try to resolve these kind of issues by re-distributing the content to multiple blocks: when that's not possible, martian will truncate the output to avoid your request resulting in an error.
If you want to disable this kind of behavior, you can use this option:
const options = {
notionLimits: {
truncate: false,
},
};
markdownToBlocks('input', options);
markdownToRichText('input', options);
You can set a callback for when one of the resulting items would exceed Notion's limits. Please note that this function will be called regardless of whether the final output will be truncated.
const options = {
notionLimits: {
// truncate: true, // by default
onError: (err: Error) => {
// Something has appened!
console.error(err);
},
},
};
markdownToBlocks('input', options);
markdownToRichText('input', options);
If an image as an invalid URL, the Notion API will reject the whole request: martian prevents this issue by converting images with invalid links into text, so that request are successfull and you can fix the links later.
If you want to disable this kind of behavior, you can use this option:
const options = {
strictImageUrls: false,
};
Default behavior:
markdownToBlocks('');
[
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [
{
"type": "text",
"annotations": {
"bold": false,
"strikethrough": false,
"underline": false,
"italic": false,
"code": false,
"color": "default"
},
"text": {
"content": "InvalidURL"
}
}
]
}
}
]
strictImageUrls disabled:
markdownToBlocks('', {
strictImageUrls: false,
});
[
{
"object": "block",
"type": "image",
"image": {
"type": "external",
"external": {
"url": "InvalidURL"
}
}
}
]
By default, if the text provided to markdownToRichText would result in one or more non-inline elements, the package will ignore those and only parse paragraphs.
You can make the package throw an error when a non-inline element is detected by setting the nonInline option to 'throw'.
Default behavior:
markdownToRichText('# Header\nAbc', {
// nonInline: 'ignore', // Default
});
[
{
type: 'text',
annotations: {
bold: false,
strikethrough: false,
underline: false,
italic: false,
code: false,
color: 'default'
},
text: { content: 'Abc', link: undefined }
}
]
Throw an error:
markdownToRichText('# Header\nAbc', {
nonInline: 'throw',
});
Error: Unsupported markdown element: {"type":"heading","depth":1,"children":[{"type":"text","value":"Header","position":{"start":{"line":1,"column":3,
"offset":2},"end":{"line":1,"column":9,"offset":8}}}],"position":{"start":{"line":1,"column":1,"offset":0},"end":{"line":1,"column":9,"offset":8}}}
Built with π by the team behind Fabric.
1,654 followers Β· starred Jul 2025
1,921 followers Β· starred Dec 2022
4,037 followers Β· starred Feb 2026
560 followers Β· starred Oct 2022