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

MK Notes uses the id field in your markdown frontmatter to track which Notion pages correspond to which markdown files. When you use the --save-id option, MK Notes automatically writes the Notion page ID back to your markdown files after synchronization.

On subsequent syncs, MK Notes uses this stored ID to update the existing Notion page instead of creating a new one.

The `id` Frontmatter Property

The id property is automatically generated when you sync with the --save-id option:

---
id: 12345678-1234-1234-1234-123456789abc
title: My Document Title
---

Your content here...

Automatically generated

You don't need to set this property manually. Use the --save-id flag when running the sync command, and MK Notes will automatically populate this field with the Notion page ID.

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.

Using Save ID (Recommended)

Use the --save-id option to enable incremental updates. This saves the Notion page ID directly to your markdown file's frontmatter after synchronization:

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

After syncing, your markdown file will be updated with the Notion page ID:

---
id: 12345678-1234-1234-1234-123456789abc
title: My Document Title
---

Your content here...

On subsequent syncs, MK Notes will use this ID to update the existing page directly.

Benefits of save-id

Using --save-id provides:

Incremental updates: Only changed content is updated
No duplicates: Existing pages are updated instead of recreated
Simple setup: No additional configuration needed in Notion
Source of truth: Your markdown files track the page mappings

Clean Sync

The --clean flag removes existing content before syncing:

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

With clean sync enabled:

Existing content in the destination is deleted
New pages are created with the updated content

Use with caution

Clean sync removes ALL existing content from the destination. Consider using --save-id instead for incremental updates that preserve your Notion page structure.

Force New Pages

The --force-new option ignores any existing page IDs stored in your markdown frontmatter and creates new pages:

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

This is useful when you want to:

Create a fresh copy of your documentation in the database
Test synchronization without affecting existing pages
Migrate content to a new database

Potential duplicates

Using --force-new without --clean will create duplicate entries in your database. If you want to replace all content, combine it with --clean:

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

Flat Structure

The --flat option flattens the page tree, making all pages direct children of the database instead of maintaining nested folder structures:

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

When syncing to databases, --flat is particularly useful because:

All pages appear at the same level in the database
Easier to filter and sort all documents uniformly
No nested hierarchy to navigate
Better for database views where you want all items visible at once

Database sync with flat

When using --flat with database sync, the root node is skipped and all files become direct database items. This creates a clean, flat list of all your documents in the database, making them easier to manage with database views and filters.

Combining Options

You can combine --save-id and --force-new with --clean for different workflows:

Options	Behavior
`--save-id`	Updates existing pages by ID, saves new IDs to frontmatter
`--force-new`	Creates new pages, ignores existing IDs
`--flat`	Flattens structure, all pages become direct children
`--clean --save-id`	Deletes old pages, creates new ones, saves new IDs
`--clean --force-new --save-id`	Full reset: deletes all, creates new pages, saves new IDs
`--flat --save-id`	Flat structure with incremental updates

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:

Notion Property Type	Frontmatter Value Format
Text	`"any string"`
Number	`123` or `45.67`
Select	`"option-name"`
Multi-select	`"option1, option2"`
Checkbox	`true` or `false`
URL	`"https://example.com"`
Email	`"user@example.com"`
Phone	`"+1234567890"`
Date	`"2024-01-15"`

Property must exist

The database property must already exist in your Notion database. MK Notes will not create new properties automatically—it only populates existing ones.

Complete Example

Here's a complete example of a markdown file after syncing with --save-id:

---
id: 12345678-1234-1234-1234-123456789abc
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...

Note

The id field is automatically generated by MK Notes when using --save-id. You only need to provide title, icon, and properties in your initial markdown file.

Best Practices

1. Use Save ID for Incremental Updates

Always use the --save-id flag to enable incremental updates and avoid duplicates:

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

2. 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

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