Your first synchronization

In this tutorial, you will learn how to synchronize your markdown files to Notion with Mk Notes.

Requirements

A Notion Integration with read-write access on your Notion page or your Notion Database
Read the official Notion guide to create and setup a Notion Integration on your workspace

Step-by-step guide 👇

Step 1: Preview the synchronization result

Before starting the synchronization, you can preview the result of the synchronization by running the following command:

  mk-notes preview-sync --input <path-to-your-markdown-file-or-directory>

You will see the Notion page architecture that will be generated based on your markdown files.

Step 2: Synchronize your markdown files

Launch the following command:

  mk-notes sync \
    --input <path-to-your-markdown-file-or-directory> \
    --destination <notion-page-or-database-url> \
    --notion-api-key <your-notion-secret>

--input : The path to your markdown file or directory containing markdown files.
--destination : The Notion page or Notion Database URL where you want to synchronize your markdown files.
--notion-api-key : Your Notion secret token.

Mk Notes supports both Notion Pages and Notion Databases as destinations. When syncing to a database, pages are created as database items.

For more information about synchronization into a database, you can read the Database Synchronization guide.

Enable incremental updates

Add --save-id to your command to save Notion page IDs back to your markdown files. This enables incremental updates on subsequent syncs, so MK Notes will update existing pages instead of creating duplicates:

mk-notes sync \
  --input <path> \
  --destination <notion-url> \
  --notion-api-key <your-secret> \
  --save-id

Going further

Mk Notes allows you to style the created Notion pages directly from your markdown. You can find more information in the Styling Notion Page guide.

Recommended for ongoing sync

If you plan to sync your documentation regularly, we recommend using the --save-id option. This saves Notion page IDs to your markdown frontmatter, enabling MK Notes to update existing pages on subsequent syncs rather than creating duplicates.

Learn more about all available options in the CLI Commands guide.