{"id":13659969,"url":"https://github.com/tryfabric/martian","last_synced_at":"2026-02-02T15:14:43.361Z","repository":{"id":39856299,"uuid":"378540371","full_name":"tryfabric/martian","owner":"tryfabric","description":"Markdown to Notion: Convert Markdown and GitHub Flavoured Markdown to Notion API Blocks and RichText 🔀📝","archived":false,"fork":false,"pushed_at":"2025-05-13T08:36:31.000Z","size":281,"stargazers_count":426,"open_issues_count":17,"forks_count":62,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-13T09:36:53.050Z","etag":null,"topics":["ast","fabric","gfm","markdown","notion"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@tryfabric/martian","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tryfabric.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-06-20T02:13:30.000Z","updated_at":"2025-05-13T08:36:34.000Z","dependencies_parsed_at":"2023-02-18T12:46:14.056Z","dependency_job_id":"588ff2c4-d640-4cfc-a1bd-30463bd7ed56","html_url":"https://github.com/tryfabric/martian","commit_stats":{"total_commits":101,"total_committers":15,"mean_commits":6.733333333333333,"dds":0.7227722772277227,"last_synced_commit":"dfae74cf1162ff9aeb812d568bcdb62e65ad597c"},"previous_names":["instantish/martian"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryfabric%2Fmartian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryfabric%2Fmartian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryfabric%2Fmartian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tryfabric%2Fmartian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tryfabric","download_url":"https://codeload.github.com/tryfabric/martian/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149803,"owners_count":22022849,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","fabric","gfm","markdown","notion"],"created_at":"2024-08-02T05:01:14.414Z","updated_at":"2026-02-02T15:14:43.354Z","avatar_url":"https://github.com/tryfabric.png","language":"TypeScript","funding_links":[],"categories":["HarmonyOS","TypeScript"],"sub_categories":["Windows Manager"],"readme":"# Martian: Markdown to Notion Parser\n\nConvert Markdown and GitHub Flavoured Markdown to Notion API Blocks and RichText.\n\n[![Node.js CI](https://github.com/tryfabric/martian/actions/workflows/ci.yml/badge.svg)](https://github.com/tryfabric/martian/actions/workflows/ci.yml)\n[![Code Style: Google](https://img.shields.io/badge/code%20style-google-blueviolet.svg)](https://github.com/google/gts)\n\nMartian is a Markdown parser to convert any Markdown content to Notion API block or RichText objects. It\nuses [unified](https://github.com/unifiedjs/unified) to create a Markdown AST, then converts the AST into Notion\nobjects.\n\nDesigned to make using the Notion SDK and API easier. Notion API version 1.0.\n\n### Supported Markdown Elements\n\n- All inline elements (italics, bold, strikethrough, inline code, hyperlinks, equations)\n- Lists (ordered, unordered, checkboxes) - to any level of depth\n- All headers (header levels \u003e= 3 are treated as header level 3)\n- Code blocks, with language highlighting support\n- Block quotes\n  - Supports GFM alerts (e.g. [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION])\n  - Supports Notion callouts when blockquote starts with an emoji (optional, enabled with `enableEmojiCallouts`)\n  - Automatically maps common emojis and alert types to appropriate background colors\n  - Preserves formatting and nested blocks within callouts\n- Tables\n- Equations\n- Images\n  - Inline images are extracted from the paragraph and added afterwards (as these are not supported in notion)\n  - Image urls are validated, if they are not valid as per the Notion external spec, they will be inserted as text for you to fix manually\n\n## Usage\n\n### Basic usage:\n\nThe package exports two functions, which you can import like this:\n\n```ts\n// JS\nconst {markdownToBlocks, markdownToRichText} = require('@tryfabric/martian');\n// TS\nimport {markdownToBlocks, markdownToRichText} from '@tryfabric/martian';\n```\n\nHere are couple of examples with both of them:\n\n```ts\nmarkdownToRichText(`**Hello _world_**`);\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\n[\n  {\n    \"type\": \"text\",\n    \"annotations\": {\n      \"bold\": true,\n      \"strikethrough\": false,\n      \"underline\": false,\n      \"italic\": false,\n      \"code\": false,\n      \"color\": \"default\"\n    },\n    \"text\": {\n      \"content\": \"Hello \"\n    }\n  },\n  {\n    \"type\": \"text\",\n    \"annotations\": {\n      \"bold\": true,\n      \"strikethrough\": false,\n      \"underline\": false,\n      \"italic\": true,\n      \"code\": false,\n      \"color\": \"default\"\n    },\n    \"text\": {\n      \"content\": \"world\"\n    }\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\n```ts\nmarkdownToBlocks(`\nhello _world_ \n*** \n## heading2\n* [x] todo\n\n\u003e 📘 **Note:** Important _information_\n\n\u003e Some other blockquote\n`);\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\n[\n  {\n    \"object\": \"block\",\n    \"type\": \"paragraph\",\n    \"paragraph\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"annotations\": {\n            \"bold\": false,\n            \"strikethrough\": false,\n            \"underline\": false,\n            \"italic\": false,\n            \"code\": false,\n            \"color\": \"default\"\n          },\n          \"text\": {\n            \"content\": \"hello \"\n          }\n        },\n        {\n          \"type\": \"text\",\n          \"annotations\": {\n            \"bold\": false,\n            \"strikethrough\": false,\n            \"underline\": false,\n            \"italic\": true,\n            \"code\": false,\n            \"color\": \"default\"\n          },\n          \"text\": {\n            \"content\": \"world\"\n          }\n        }\n      ]\n    }\n  },\n  {\n    \"object\": \"block\",\n    \"type\": \"divider\",\n    \"divider\": {}\n  },\n  {\n    \"object\": \"block\",\n    \"type\": \"heading_2\",\n    \"heading_2\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"annotations\": {\n            \"bold\": false,\n            \"strikethrough\": false,\n            \"underline\": false,\n            \"italic\": false,\n            \"code\": false,\n            \"color\": \"default\"\n          },\n          \"text\": {\n            \"content\": \"heading2\"\n          }\n        }\n      ]\n    }\n  },\n  {\n    \"object\": \"block\",\n    \"type\": \"to_do\",\n    \"to_do\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"annotations\": {\n            \"bold\": false,\n            \"strikethrough\": false,\n            \"underline\": false,\n            \"italic\": false,\n            \"code\": false,\n            \"color\": \"default\"\n          },\n          \"text\": {\n            \"content\": \"todo\"\n          }\n        }\n      ],\n      \"checked\": true\n    }\n  },\n  {\n    \"type\": \"callout\",\n    \"callout\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"text\": {\n            \"content\": \"Note:\"\n          },\n          \"annotations\": {\n            \"bold\": true,\n            \"strikethrough\": false,\n            \"underline\": false,\n            \"italic\": false,\n            \"code\": false,\n            \"color\": \"default\"\n          }\n        },\n        {\n          \"type\": \"text\",\n          \"text\": {\n            \"content\": \" Important \"\n          }\n        },\n        {\n          \"type\": \"text\",\n          \"text\": {\n            \"content\": \"information\"\n          },\n          \"annotations\": {\n            \"bold\": false,\n            \"strikethrough\": false,\n            \"underline\": false,\n            \"italic\": true,\n            \"code\": false,\n            \"color\": \"default\"\n          }\n        }\n      ],\n      \"icon\": {\n        \"type\": \"emoji\",\n        \"emoji\": \"📘\"\n      },\n      \"color\": \"blue_background\"\n    }\n  },\n  {\n    \"type\": \"quote\",\n    \"quote\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"text\": {\n            \"content\": \"Some other blockquote\"\n          },\n          \"annotations\": {\n            \"bold\": false,\n            \"strikethrough\": false,\n            \"underline\": false,\n            \"italic\": false,\n            \"code\": false,\n            \"color\": \"default\"\n          }\n        }\n      ]\n    }\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\n### Working with blockquotes\n\nMartian supports three types of blockquotes:\n\n1. Standard blockquotes:\n\n```md\n\u003e This is a regular blockquote\n\u003e It can span multiple lines\n```\n\n2. GFM alerts (based on [GFM Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)):\n\n```md\n\u003e [!NOTE]\n\u003e Important information that users should know\n\n\u003e [!WARNING]\n\u003e Critical information that needs attention\n```\n\n3. Emoji-style callouts (optional) (based on [ReadMe's markdown callouts](https://docs.readme.com/rdmd/docs/callouts)):\n\n```md\n\u003e 📘 **Note:** This is a callout with a blue background\n\u003e It supports all markdown formatting and can span multiple lines\n\n\u003e ❗ **Warning:** This is a callout with a red background\n\u003e Perfect for important warnings\n```\n\n#### GFM Alerts\n\nGFM alerts are automatically converted to Notion callouts with appropriate icons and colors:\n\n- NOTE (📘, blue): Useful information that users should know\n- TIP (💡, green): Helpful advice for doing things better\n- IMPORTANT (☝️, purple): Key information users need to know\n- WARNING (⚠️, yellow): Urgent info that needs immediate attention\n- CAUTION (❗, red): Advises about risks or negative outcomes\n\n#### Emoji-style Callouts\n\nBy default, emoji-style callouts are disabled. You can enable them using the `enableEmojiCallouts` option:\n\n```ts\nconst options = {\n  enableEmojiCallouts: true,\n};\n```\n\nWhen 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:\n\n- 📘 (blue): Perfect for notes and information\n- 👍 (green): Success messages and tips\n- ❗ (red): Warnings and important notices\n- 🚧 (yellow): Work in progress or caution notices\n\nAll other emojis will have a default background color. The supported emoji color mappings can be expanded easily if needed.\n\nIf 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.\n\n##### Examples\n\nStandard blockquote:\n\n```ts\nmarkdownToBlocks('\u003e A regular blockquote');\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\n[\n  {\n    \"object\": \"block\",\n    \"type\": \"quote\",\n    \"quote\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"text\": {\n            \"content\": \"A regular blockquote\"\n          }\n        }\n      ]\n    }\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\nGFM alert:\n\n```ts\nmarkdownToBlocks('\u003e [!NOTE]\\n\u003e Important information');\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\n[\n  {\n    \"object\": \"block\",\n    \"type\": \"callout\",\n    \"callout\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"text\": {\n            \"content\": \"Note\"\n          }\n        }\n      ],\n      \"icon\": {\n        \"type\": \"emoji\",\n        \"emoji\": \"ℹ️\"\n      },\n      \"color\": \"blue_background\",\n      \"children\": [\n        {\n          \"type\": \"paragraph\",\n          \"paragraph\": {\n            \"rich_text\": [\n              {\n                \"type\": \"text\",\n                \"text\": {\n                  \"content\": \"Important information\"\n                }\n              }\n            ]\n          }\n        }\n      ]\n    }\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\nEmoji-style callout (with `enableEmojiCallouts: true`):\n\n```ts\nmarkdownToBlocks('\u003e 📘 Note: Important information', {\n  enableEmojiCallouts: true,\n});\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\n[\n  {\n    \"object\": \"block\",\n    \"type\": \"callout\",\n    \"callout\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"text\": {\n            \"content\": \"Note: Important information\"\n          }\n        }\n      ],\n      \"icon\": {\n        \"type\": \"emoji\",\n        \"emoji\": \"📘\"\n      },\n      \"color\": \"blue_background\"\n    }\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\n### Working with Notion's limits\n\nSometimes a Markdown input would result in an output that would be rejected by the Notion API: here are some options to deal with that.\n\n#### An item exceeds the children or character limit\n\nBy 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.  \nIf you want to disable this kind of behavior, you can use this option:\n\n```ts\nconst options = {\n  notionLimits: {\n    truncate: false,\n  },\n};\n\nmarkdownToBlocks('input', options);\nmarkdownToRichText('input', options);\n```\n\n#### Manually handling errors related to Notions's limits\n\nYou 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.\n\n```ts\nconst options = {\n  notionLimits: {\n    // truncate: true, // by default\n    onError: (err: Error) =\u003e {\n      // Something has appened!\n      console.error(err);\n    },\n  },\n};\n\nmarkdownToBlocks('input', options);\nmarkdownToRichText('input', options);\n```\n\n### Working with images\n\nIf 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.  \nIf you want to disable this kind of behavior, you can use this option:\n\n```ts\nconst options = {\n  strictImageUrls: false,\n};\n```\n\nDefault behavior:\n\n```ts\nmarkdownToBlocks('![](InvalidURL)');\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\n[\n  {\n    \"object\": \"block\",\n    \"type\": \"paragraph\",\n    \"paragraph\": {\n      \"rich_text\": [\n        {\n          \"type\": \"text\",\n          \"annotations\": {\n            \"bold\": false,\n            \"strikethrough\": false,\n            \"underline\": false,\n            \"italic\": false,\n            \"code\": false,\n            \"color\": \"default\"\n          },\n          \"text\": {\n            \"content\": \"InvalidURL\"\n          }\n        }\n      ]\n    }\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\n`strictImageUrls` disabled:\n\n```ts\nmarkdownToBlocks('![](InvalidURL)', {\n  strictImageUrls: false,\n});\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\n[\n  {\n    \"object\": \"block\",\n    \"type\": \"image\",\n    \"image\": {\n      \"type\": \"external\",\n      \"external\": {\n        \"url\": \"InvalidURL\"\n      }\n    }\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\n### Non-inline elements when parsing rich text\n\nBy 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.  \nYou can make the package throw an error when a non-inline element is detected by setting the `nonInline` option to `'throw'`.\n\nDefault behavior:\n\n```ts\nmarkdownToRichText('# Header\\nAbc', {\n  // nonInline: 'ignore', // Default\n});\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\n[\n  {\n    type: 'text',\n    annotations: {\n      bold: false,\n      strikethrough: false,\n      underline: false,\n      italic: false,\n      code: false,\n      color: 'default'\n    },\n    text: { content: 'Abc', link: undefined }\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\nThrow an error:\n\n```ts\nmarkdownToRichText('# Header\\nAbc', {\n  nonInline: 'throw',\n});\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eResult\u003c/summary\u003e\n\u003cpre\u003e\nError: Unsupported markdown element: {\"type\":\"heading\",\"depth\":1,\"children\":[{\"type\":\"text\",\"value\":\"Header\",\"position\":{\"start\":{\"line\":1,\"column\":3,\n\"offset\":2},\"end\":{\"line\":1,\"column\":9,\"offset\":8}}}],\"position\":{\"start\":{\"line\":1,\"column\":1,\"offset\":0},\"end\":{\"line\":1,\"column\":9,\"offset\":8}}}  \n\u003c/pre\u003e\n\u003c/details\u003e\n\n---\n\nBuilt with 💙 by the team behind [Fabric](https://tryfabric.com).\n\n\u003cimg src=\"https://static.scarf.sh/a.png?x-pxid=79ae4e0a-7e48-4965-8a83-808c009aa47a\" /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftryfabric%2Fmartian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftryfabric%2Fmartian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftryfabric%2Fmartian/lists"}