Database Synchronization

This guide explains how to sync your markdown content to Notion databases instead of regular pages, enabling you to leverage Notion's powerful database features like filtering, sorting, and views.

Why Use Database Sync?

Syncing to a Notion database offers several advantages over regular page sync:

• Better organization: Use Notion's table, board, gallery, or calendar views
• Filtering & sorting: Quickly find content using database filters
• Custom properties: Add metadata like status, tags, or dates to your pages
• Scalable: Ideal for managing large collections of documents

Setting Up Your Database

Before syncing, you need to prepare your Notion database with a special property.

Creating the mk-notes-id Property

For MK Notes to identify and update existing pages (when using --clean mode), your database must have a text property named mk-notes-id.

Configuring Your Markdown Files

The id Frontmatter Property

To enable page identification and updates, add an id property to your markdown frontmatter:

---
id: my-unique-page-id
title: My Document Title
---

Your content here...

When syncing to a database:

1. The id value from your frontmatter is stored in the mk-notes-id database property
2. MK Notes uses this ID to find and update existing pages during clean sync
3. Without an id, pages will be created but cannot be updated via clean sync

Syncing Commands

Basic Database Sync

To sync markdown files to a database:

mk-notes sync \
  --input ./docs \
  --destination https://notion.so/myworkspace/database-123456 \
  --notion-api-key secret_abc123...

This creates new pages in the database for each markdown file. However, running this command multiple times will create duplicate entries.

Clean Sync (Recommended)

For updating existing content, use the --clean flag:

mk-notes sync \
  --input ./docs \
  --destination https://notion.so/myworkspace/database-123456 \
  --notion-api-key secret_abc123... \
  --clean

With clean sync enabled:

1. MK Notes searches for existing pages with matching mk-notes-id values
2. Found pages are deleted
3. New pages are created with the updated content

Adding Custom Database Properties

You can populate additional database properties directly from your markdown frontmatter using the properties field:

---
id: api-auth-guide
title: Authentication Guide
properties:
  - name: status
    value: published
  - name: category
    value: API
  - name: priority
    value: high
---

Your content here...

Supported Property Types

MK Notes automatically maps values to the appropriate Notion property type based on your database schema:

Complete Example

Here's a complete example of a markdown file optimized for database sync:

---
id: getting-started-installation
title: Installation Guide
icon: 🚀
properties:
  - name: status
    value: published
  - name: category
    value: Getting Started
  - name: last-updated
    value: 2024-01-15
---

## Introduction

Welcome to the installation guide...

## Prerequisites

Before you begin, ensure you have...

## Installation Steps

1. First, install the package...

Best Practices

1. Always Use Unique IDs

Ensure each markdown file has a unique id to prevent conflicts:

---
id: docs/guides/authentication # Use path-based IDs for uniqueness
title: Authentication
---

2. Use Clean Sync for Updates

Always use the --clean flag when updating existing content to avoid duplicates:

mk-notes sync -i ./docs -d <database-url> -k <api-key> --clean

3. Preview Before Syncing

Use the preview command to verify your structure:

mk-notes preview-sync --input ./docs

4. Organize with Database Views

After syncing, create Notion database views to organize your content:

• Table view: For detailed property inspection
• Board view: Group by status or category
• Gallery view: Visual overview of your documentation

Troubleshooting

Pages are duplicated

Cause: Running sync without --clean flag, or missing id in frontmatter.

Solution: Add unique id values to all markdown files and use --clean flag.

Properties not appearing

Cause: Property doesn't exist in the database or name doesn't match exactly.

Solution: Ensure the property exists in your Notion database with the exact same name (case-sensitive).

Clean sync not deleting old pages

Cause: The mk-notes-id property doesn't exist or has a different name.

Solution: Create a text property named exactly mk-notes-id in your database.

For more information about CLI commands, see the CLI Commands documentation.