{"id":13625374,"url":"https://github.com/souvikinator/notion-to-md","last_synced_at":"2025-05-14T14:07:32.271Z","repository":{"id":38096105,"uuid":"434904623","full_name":"souvikinator/notion-to-md","owner":"souvikinator","description":"Convert Notion pages, blocks, or entire lists into any format: Markdown, MDX, JSX, HTML, LaTeX, and more. A powerful Notion conversion engine that lets you write once in Notion and publish seamlessly anywhere, in any format. Compatible with your favorite CMS, workflow, static site generator, and beyond.","archived":false,"fork":false,"pushed_at":"2025-05-12T17:41:10.000Z","size":1926,"stargazers_count":1328,"open_issues_count":20,"forks_count":105,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-12T18:41:48.226Z","etag":null,"topics":["exporter","hacktoberfest","markdown","md","nodejs","notion","notion-api","notion-client","notion-convert","notion-database","notion-export","notion-exporter","notion-markdown","notion-to-anything","notion-to-html","notion-to-md","notion2md"],"latest_commit_sha":null,"homepage":"https://notionconvert.com/docs/v4","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/souvikinator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"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},"funding":{"github":"souvikinator","patreon":null,"open_collective":null,"ko_fi":"souvikinator","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2021-12-04T13:11:08.000Z","updated_at":"2025-05-12T17:36:09.000Z","dependencies_parsed_at":"2024-06-18T12:31:48.088Z","dependency_job_id":"ad038efe-f520-4455-9bcc-686cf27451ff","html_url":"https://github.com/souvikinator/notion-to-md","commit_stats":{"total_commits":207,"total_committers":26,"mean_commits":7.961538461538462,"dds":0.3913043478260869,"last_synced_commit":"37ec5811a09b31aaa5aabf0b7d9f28cbab509a89"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souvikinator%2Fnotion-to-md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souvikinator%2Fnotion-to-md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souvikinator%2Fnotion-to-md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/souvikinator%2Fnotion-to-md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/souvikinator","download_url":"https://codeload.github.com/souvikinator/notion-to-md/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253805848,"owners_count":21967053,"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":["exporter","hacktoberfest","markdown","md","nodejs","notion","notion-api","notion-client","notion-convert","notion-database","notion-export","notion-exporter","notion-markdown","notion-to-anything","notion-to-html","notion-to-md","notion2md"],"created_at":"2024-08-01T21:01:54.714Z","updated_at":"2025-05-14T14:07:32.265Z","avatar_url":"https://github.com/souvikinator.png","language":"TypeScript","funding_links":["https://github.com/sponsors/souvikinator","https://ko-fi.com/souvikinator"],"categories":["TypeScript","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"\n\n\u003c!-- \n💡 For better readability and detailed instructions head over to the [wiki](https://github.com/souvikinator/notion-to-md/wiki). \n--\u003e\n\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n\u003cimg src=\"https://i.ibb.co/Pzyf13S/Group-168.png\" alt=\"notion-to-md banner\"  width=\"750\" /\u003e\n  \u003cbr\u003e\n  \u003cb\u003eNotion-to-MD\u003c/b\u003e\n  \u003cbr\u003e\n  \u003csub\u003e\u003csup\u003e\u003cb\u003e(Notion to Markdown)\u003c/b\u003e\u003c/sup\u003e\u003c/sub\u003e\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://notionconvert.com/notion-to-md/docs/v4/getting-started/\"\u003e\n    \u003cimg src=\"https://i.ibb.co/4Zv3dzRd/Group-52-1.png\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/drWw5Ya535\"\u003e\n    \u003cimg src=\"https://i.ibb.co/ZTk7QCW/Group-186.png\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.reddit.com/r/notion_to_md/\"\u003e\n    \u003cimg src=\"https://i.ibb.co/vBN5Cgz/Frame-4.png\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n       Notion-to-MD is a Node.js package that allows you to convert Notion pages to Markdown format. \n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Convert notion pages, blocks and list of blocks to markdown (supports nesting) using \u003ca href=\"https://github.com/makenotion/notion-sdk-js\"\u003enotion-sdk-js\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://img.shields.io/github/stars/souvikinator/notion-to-md?style=flat\" alt=\"github stars\"\u003e\n\u003cimg src=\"https://img.shields.io/twitter/follow/souvikinator?color=blue\u0026logo=x\u0026style=flat\" alt=\"twitter\" /\u003e\n\u003cimg src=\"https://komarev.com/ghpvc/?username=notion-to-md\u0026abbreviated=true\u0026label=REPO+VIEWS\" alt=\"repo views\" /\u003e\n\u003c/p\u003e\n\n## 🗒️ Recent posts\n\n\u003c!-- feed start --\u003e\n- Apr 23 - [Mastering Media Handling in notion-to-md v4 - Download, Upload, and Direct Strategies](https://notionconvert.com/blog/mastering-media-handling-in-notion-to-md-v4/)\n- Mar 12 - [How to Convert Notion Properties to Frontmatter with notion-to-md v4](https://notionconvert.com/blog/how-to-convert-notion-properties-to-frontmatter/)\n- Mar 12 - [How to Handle Documents in Notion Using notion-to-md v4](https://notionconvert.com/blog/how-to-handle-documents-in-notion-using-notion-to-md-v4/)\n- Mar 11 - [How to Convert Notion Comments to Markdown Footnotes with notion-to-md v4](https://notionconvert.com/blog/how-to-use-notion-comments-as-footnotes-in-markdown/)\n\u003c!-- feed end --\u003e\n\n\n## Looking for Support in Other Languages?\n\u003e If you've created a specific client, please open an issue to have it added here.\n\n- [notion-to-md-py](https://github.com/SwordAndTea/notion-to-md-py) by [@SwordAndTea](https://github.com/SwordAndTea)\n\n## Install\n\n```Bash\nnpm install notion-to-md\n```\n\n## Usage\n\u003e ⚠️ **Note:** Before getting started, create [an integration and find the token](https://www.notion.so/my-integrations).\n\u003e  Details on methods can be found in [API section](https://github.com/souvikinator/notion-to-md#api)\n\n\u003e ⚠️ **Note:** Starting from v2.7.0, `toMarkdownString` no longer automatically saves child pages. \n\u003e Now it provides an object containing the markdown content of child pages.\n\n## converting markdown objects to markdown string\n\nThis is how the notion page looks for this example:\n\n\u003cimg src=\"https://imgur.com/O6bKCmH.png\"  width=\"500\"  /\u003e\n\n```javascript\nconst { Client } = require(\"@notionhq/client\");\nconst { NotionToMarkdown } = require(\"notion-to-md\");\nconst fs = require('fs');\n// or\n// import {NotionToMarkdown} from \"notion-to-md\";\n\nconst notion = new Client({\n  auth: \"your integration token\",\n});\n\n// passing notion client to the option\nconst n2m = new NotionToMarkdown({ notionClient: notion });\n\n(async () =\u003e {\n  const mdblocks = await n2m.pageToMarkdown(\"target_page_id\");\n  const mdString = n2m.toMarkdownString(mdblocks);\n  console.log(mdString.parent);\n})();\n```\n\u003cimg src=\"https://imgur.com/XrUYrZ0.png\"  width=\"500\"  /\u003e\n\n## Separate child page content\n\n**parent page content:**\n\n\u003cimg src=\"https://github.com/souvikinator/notion-to-md/assets/64456160/531ef45d-2dc7-47f4-bbb3-12d6fd44d299\" width=\"500\" /\u003e\n\n**child page content:**\n\n\u003cimg src=\"https://github.com/souvikinator/notion-to-md/assets/64456160/7dde090b-7333-46f8-b6df-e6c9a7b62fa9\" width=\"500\" /\u003e\n\n`NotionToMarkdown` takes second argument, `config`\n\n```javascript\nconst { Client } = require(\"@notionhq/client\");\nconst { NotionToMarkdown } = require(\"notion-to-md\");\nconst fs = require('fs');\n// or\n// import {NotionToMarkdown} from \"notion-to-md\";\n\nconst notion = new Client({\n  auth: \"your integration token\",\n});\n\n// passing notion client to the option\nconst n2m = new NotionToMarkdown({ \n  notionClient: notion,\n    config:{\n     separateChildPage:true, // default: false\n  }\n });\n\n(async () =\u003e {\n  const mdblocks = await n2m.pageToMarkdown(\"target_page_id\");\n  const mdString = n2m.toMarkdownString(mdblocks);\n  \n  console.log(mdString);\n})();\n```\n\n**Output:**\n\n`toMarkdownString` returns an object with target page content corresponding to `parent` property and if any child page exists then it's included in the same object.\n\n\u003cimg src=\"https://github.com/souvikinator/notion-to-md/assets/64456160/99bcc14e-46e6-4bed-912d-8b9300c214c1\" width=\"500\" /\u003e\n\nUser gets to save the content separately.\n\n## Disable child page parsing\n\n```javascript\n...\n\nconst n2m = new NotionToMarkdown({ \n  notionClient: notion,\n    config:{\n     parseChildPages:false, // default: parseChildPages\n  }\n });\n\n...\n```\n\n## converting page to markdown object\n\n**Example notion page:**\n\n\u003cimg src=\"https://imgur.com/9iqRpBl.png\"  width=\"500\"  /\u003e\n\n```js\nconst { Client } = require(\"@notionhq/client\");\nconst { NotionToMarkdown } = require(\"notion-to-md\");\n\nconst notion = new Client({\n  auth: \"your integration token\",\n});\n\n// passing notion client to the option\nconst n2m = new NotionToMarkdown({ notionClient: notion });\n\n(async () =\u003e {\n  // notice second argument, totalPage.\n  const x = await n2m.pageToMarkdown(\"target_page_id\", 2);\n  console.log(x);\n})();\n```\n\n**Output:**\n\n```json\n[\n  {\n    \"parent\": \"# heading 1\",\n    \"children\": []\n  },\n  {\n    \"parent\": \"- bullet 1\",\n    \"children\": [\n      {\n        \"parent\": \"- bullet 1.1\",\n        \"children\": []\n      },\n      {\n        \"parent\": \"- bullet 1.2\",\n        \"children\": []\n      }\n    ]\n  },\n  {\n    \"parent\": \"- bullet 2\",\n    \"children\": []\n  },\n  {\n    \"parent\": \"- [ ] check box 1\",\n    \"children\": [\n      {\n        \"parent\": \"- [x] check box 1.2\",\n        \"children\": []\n      },\n      {\n        \"parent\": \"- [ ] check box 1.3\",\n        \"children\": []\n      }\n    ]\n  },\n  {\n    \"parent\": \"- [ ] checkbox 2\",\n    \"children\": []\n  }\n]\n```\n\n## converting list of blocks to markdown object\n\n```js\nconst { Client } = require(\"@notionhq/client\");\nconst { NotionToMarkdown } = require(\"notion-to-md\");\n\nconst notion = new Client({\n  auth: \"your integration token\",\n});\n\n// passing notion client to the option\nconst n2m = new NotionToMarkdown({ notionClient: notion });\n\n(async () =\u003e {\n  // get all blocks in the page\n  const { results } = await notion.blocks.children.list({\n    block_id,\n  });\n\n  //convert to markdown\n  const x = await n2m.blocksToMarkdown(results);\n  console.log(x);\n})();\n```\n\n**Output**: same as before\n\n## Converting a single block to markdown string\n\n- only takes a single notion block and returns corresponding markdown string\n- nesting is ignored\n- depends on @notionhq/client\n\n```js\nconst { NotionToMarkdown } = require(\"notion-to-md\");\n\n// passing notion client to the option\nconst n2m = new NotionToMarkdown({ notionClient: notion });\n\nconst result = n2m.blockToMarkdown(block);\nconsole.log(result);\n```\n\n**result**:\n\n```\n![image](https://media.giphy.com/media/Ju7l5y9osyymQ/giphy.gif)\n```\n\n## Custom Transformers\n\nYou can define your own custom transformer for a notion type, to parse and return your own string.\n`setCustomTransformer(type, func)` will overload the parsing for the giving type.\n\n```ts\nconst { NotionToMarkdown } = require(\"notion-to-md\");\nconst n2m = new NotionToMarkdown({ notionClient: notion });\nn2m.setCustomTransformer(\"embed\", async (block) =\u003e {\n  const { embed } = block as any;\n  if (!embed?.url) return \"\";\n  return `\u003cfigure\u003e\n  \u003ciframe src=\"${embed?.url}\"\u003e\u003c/iframe\u003e\n  \u003cfigcaption\u003e${await n2m.blockToMarkdown(embed?.caption)}\u003c/figcaption\u003e\n\u003c/figure\u003e`;\n});\nconst result = n2m.blockToMarkdown(block);\n// Result will now parse the `embed` type with your custom function.\n```\n\n**Note** Be aware that `setCustomTransformer` will take only the last function for the given type. You can't set two different transforms for the same type.\n\nYou can also use the default parsing by returning `false` in your custom transformer.\n\n```ts\n// ...\nn2m.setCustomTransformer(\"embed\", async (block) =\u003e {\n  const { embed } = block as any;\n  if (embed?.url?.includes(\"myspecialurl.com\")) {\n    return `...`; // some special rendering\n  }\n  return false; // use default behavior\n});\nconst result = n2m.blockToMarkdown(block);\n// Result will now only use custom parser if the embed url matches a specific url\n```\n\n## Contribution\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\nPlease make sure to update tests as appropriate.\n\n## Contributers\n\n\u003ca href=\"https://github.com/souvikinator/notion-to-md/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=souvikinator/notion-to-md\" /\u003e\n\u003c/a\u003e\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouvikinator%2Fnotion-to-md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsouvikinator%2Fnotion-to-md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouvikinator%2Fnotion-to-md/lists"}