### Install Documentation Dependencies

Source: https://github.com/myastr0/mk-notes/blob/master/CONTRIBUTING.md

Navigate to the docs directory and install its specific dependencies.

```sh
cd docs
yarn install
```

--------------------------------

### Install Mk Notes CLI

Source: https://context7.com/myastr0/mk-notes/llms.txt

Install the Mk Notes CLI tool globally using npm or yarn. Verify the installation by checking the version.

```bash
npm install -g @mk-notes/cli
# Verify installation
mk-notes --version
```

--------------------------------

### Install Mk Notes

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/programmatic-usage.mdx

Install the Mk Notes library using npm.

```bash
npm install mk-notes
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/myastr0/mk-notes/blob/master/CONTRIBUTING.md

Install all necessary project dependencies using Yarn.

```sh
yarn install
```

--------------------------------

### Install Mk Notes CLI

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/getting-started/0-installation.mdx

Installs the Mk Notes command-line interface globally using a package manager.

```package-install
-g @mk-notes/cli
```

--------------------------------

### Run Development Server

Source: https://github.com/myastr0/mk-notes/blob/master/docs/README.md

Commands to start the Next.js development server using npm, pnpm, or yarn.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

--------------------------------

### Verify Mk Notes Installation

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/getting-started/0-installation.mdx

Checks the installed version of the Mk Notes CLI to confirm successful setup.

```bash
  mk-notes --version
```

--------------------------------

### Sync Documentation on Release

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

Example workflow to sync documentation to Notion when a new release is published.

```APIDOC
## POST /sync (Release Sync Example)

### Description
Synchronizes documentation to Notion automatically upon a GitHub release.

### Method
POST

### Endpoint
/sync

### Parameters
#### Query Parameters
- **input** (string) - Required - The path to the markdown file or directory to synchronize.
- **destination** (string) - Required - The Notion page or database URL where you want to synchronize your markdown files.
- **notion-api-key** (string) - Required - Your Notion secret token.

### Request Example
```yaml
name: Sync Docs to Notion

on:
  release:
    types: [published]

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync documentation to Notion
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

### Response
#### Success Response (200)
This action does not produce any outputs.

#### Response Example
{}
```

--------------------------------

### Preview Before Sync Workflow

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/1-preview-action.mdx

Full workflow example that previews changes on pull requests and conditionally syncs on push events.

```yaml
name: Preview and Sync

on:
  pull_request:
    paths: ['docs/**']

jobs:
  preview-and-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Preview synchronization
        uses: Myastr0/mk-notes/preview
        with:
          input: './docs'
          format: 'plainText'
          output: './preview.txt'

      - name: Upload preview
        uses: actions/upload-artifact@v4
        with:
          name: sync-preview
          path: ./preview.txt

      - name: Sync to Notion
        if: github.event_name == 'push'
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

--------------------------------

### Install Mk Notes CLI

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/blog/2025-11-30-v3-database-support/index.mdx

Update to the latest version of the Mk Notes CLI via npm.

```bash
npm install -g @mk-notes/cli@latest
```

--------------------------------

### Sync Documentation on Release

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

This example demonstrates how to automatically sync documentation to Notion when a new release is published. It requires checkout, the sync action, and your Notion API key and destination URL stored as secrets.

```yaml
name: Sync Docs to Notion

on:
  release:
    types: [published]

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync documentation to Notion
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

--------------------------------

### Complete Markdown Example with Frontmatter

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/database-sync.mdx

An example of a markdown file with frontmatter including `id`, `title`, `icon`, and `properties` after syncing with `--save-id`.

```markdown
---
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...
```

--------------------------------

### Define File Organization Structure

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/architecture.mdx

Example directory layout showing how index files and subdirectories are structured for MK Notes.

```text
docs/
├── getting-started/
│   ├── index.md
│   ├── installation.md
│   └── configuration.md
├── guides/
│   ├── basic-usage.md
│   └── advanced-features/
│       └── customization.md
└── api-reference.md
```

--------------------------------

### Generate JSON Preview Workflow

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/1-preview-action.mdx

Workflow example for generating a structured JSON preview on a weekly schedule.

```yaml
name: Generate JSON Preview

on:
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  generate-preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate JSON preview
        uses: Myastr0/mk-notes/preview
        with:
          input: './docs'
          format: 'json'
          output: './docs-structure.json'

      - name: Upload JSON preview
        uses: actions/upload-artifact@v4
        with:
          name: docs-structure
          path: ./docs-structure.json
```

--------------------------------

### Sync to a Notion Database

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

This example shows how to sync markdown files to a Notion database. Pages will be created as database items, allowing you to leverage Notion's database features. It requires checkout, the sync action, and Notion credentials as secrets.

```yaml
name: Sync to Notion Database

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  sync-to-database:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync to Notion database
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DATABASE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

--------------------------------

### Sync to a Notion Database

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

Example workflow for syncing markdown files to a Notion database.

```APIDOC
## POST /sync (Sync to Database Example)

### Description
Synchronizes markdown files to a specified Notion database, creating each markdown file as an item within the database.

### Method
POST

### Endpoint
/sync

### Parameters
#### Query Parameters
- **input** (string) - Required - The path to the markdown file or directory to synchronize.
- **destination** (string) - Required - The URL of the Notion database where you want to synchronize your markdown files.
- **notion-api-key** (string) - Required - Your Notion secret token.

### Request Example
```yaml
name: Sync to Notion Database

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  sync-to-database:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync to Notion database
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DATABASE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

### Response
#### Success Response (200)
This action does not produce any outputs.

#### Response Example
{}
```

--------------------------------

### Demonstrate list nesting limits

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/writing/notion-limitations.mdx

Examples of invalid and valid list structures based on the 3-level nesting constraint.

```markdown
- Level 1
  - Level 2
    - Level 3
      - Level 4 (❌ This will cause an error)
```

```markdown
- Level 1
  - Level 2
    - Level 3 (✅ Maximum supported depth)
```

--------------------------------

### Clean Sync with Warning

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

Example workflow demonstrating a clean sync, which removes all existing content from the destination before syncing.

```APIDOC
## POST /sync (Clean Sync Example)

### Description
Performs a clean synchronization to Notion, ensuring the destination is cleared of all previous content before the new content is synced.

### Method
POST

### Endpoint
/sync

### Parameters
#### Query Parameters
- **input** (string) - Required - The path to the markdown file or directory to synchronize.
- **destination** (string) - Required - The Notion page or database URL where you want to synchronize your markdown files.
- **notion-api-key** (string) - Required - Your Notion secret token.
- **clean** (boolean) - Required - Set to `true` to enable clean sync mode.

### Request Example
```yaml
name: Clean Sync Documentation

on:
  workflow_dispatch:

jobs:
  clean-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Clean sync to Notion
        uses: Myastr0/mk-notes/sync
        with:
          input: './content'
          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
          clean: 'true'
```

### Response
#### Success Response (200)
This action does not produce any outputs.

#### Response Example
{}
```

--------------------------------

### Sync on Push to Main Branch

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

Example workflow to automatically sync content to Notion when changes are pushed to the main branch.

```APIDOC
## POST /sync (Push to Main Sync Example)

### Description
Synchronizes content to Notion automatically on push events to the main branch, specifically for changes within the 'docs' directory.

### Method
POST

### Endpoint
/sync

### Parameters
#### Query Parameters
- **input** (string) - Required - The path to the markdown file or directory to synchronize.
- **destination** (string) - Required - The Notion page or database URL where you want to synchronize your markdown files.
- **notion-api-key** (string) - Required - Your Notion secret token.

### Request Example
```yaml
name: Auto-sync to Notion

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync to Notion
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

### Response
#### Success Response (200)
This action does not produce any outputs.

#### Response Example
{}
```

--------------------------------

### Sync to Different Notion Pages by Branch

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/best-practices.mdx

Use conditional logic to sync to different Notion pages based on the branch. This example syncs to a production page for the main branch and a development page for others.

```yaml
- name: Sync to Notion
  uses: Myastr0/mk-notes/sync
  with:
    input: './docs'
    destination: ${{ github.ref == 'refs/heads/main' && secrets.NOTION_MAIN_DOCS_PAGE_URL || secrets.NOTION_DEV_DOCS_PAGE_URL }}
    notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/myastr0/mk-notes/blob/master/CONTRIBUTING.md

Run the documentation server from the root directory of the project.

```sh
yarn doc:serve
```

--------------------------------

### Initialize MkNotes Client and Preview Sync

Source: https://context7.com/myastr0/mk-notes/llms.txt

Initializes the MkNotes client with API key and log level, then performs a preview synchronization to a text file.

```typescript
import MkNotes from '@mk-notes/cli';

// Initialize the client
const client = new MkNotes({
  notionApiKey: process.env.NOTION_API_KEY,
  LOG_LEVEL: 'info', // 'error' | 'warn' | 'info' | 'debug'
});

// Preview synchronization
const preview = await client.previewSynchronization({
  inputPath: './docs/',
  format: 'plainText', // or 'json'
  output: './preview.txt', // optional: save to file
});
console.log(preview);
```

--------------------------------

### Mk Notes CLI: Preview Sync in JSON Format

Source: https://context7.com/myastr0/mk-notes/llms.txt

Generate a preview of the sync operation with the output formatted as JSON. This can be useful for programmatic inspection of the planned Notion structure.

```bash
mk-notes preview-sync --input ./docs --format json
```

--------------------------------

### Markdown Frontmatter Structure

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/writing/styling-notion-page.mdx

Example of the basic frontmatter structure required at the beginning of a markdown file for Mk Notes.

```markdown
# Beginning of your markdown file

---

id: unique-page-identifier
title: The notion page title
icon: 💡

---
```

--------------------------------

### Sync with --force-new

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/blog/2025-12-11-v3.1-incremental-sync/index.mdx

Use the --force-new flag to ignore existing IDs and create fresh pages in the destination.

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

--------------------------------

### Test Mk Notes CLI Locally

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/troubleshooting.mdx

Use the Mk Notes CLI to test your configuration locally before committing to GitHub Actions. The `preview` command helps verify structure, while `sync` can be used with caution.

```bash
npx mk-notes preview ./docs --format plainText
```

```bash
npx mk-notes sync ./docs --destination "your-page-url" --api-key "your-key"
```

--------------------------------

### Preview and Sync Changes

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/best-practices.mdx

Use the preview action before syncing to verify structure. Sync to Notion only on the main branch.

```yaml
- name: Preview changes
  uses: Myastr0/mk-notes/preview
  with:
    input: './docs'
    format: 'plainText'

- name: Sync to Notion
  if: github.ref == 'refs/heads/main'
  uses: Myastr0/mk-notes/sync
  with:
    input: './docs'
    destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
    notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

--------------------------------

### Setting Notion Page Title in Frontmatter

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/writing/styling-notion-page.mdx

Example of the 'title' property in frontmatter, used to specify the title for the Notion page.

```markdown
title: <string>
```

--------------------------------

### Mk Notes CLI: Preview Sync with Flat Structure

Source: https://context7.com/myastr0/mk-notes/llms.txt

Preview the sync operation with a flat structure. This shows how files would be organized as direct children of the destination, ignoring the original directory hierarchy.

```bash
mk-notes preview-sync --input ./docs --flat
```

--------------------------------

### Handle Notion API validation error

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/writing/notion-limitations.mdx

Example of the error message returned when exceeding the maximum list nesting depth.

```text
APIResponseError: body failed validation: body.children[0].bulleted_list_item.children[0].bulleted_list_item.children[0].bulleted_list_item.children should be not present
```

--------------------------------

### Preview Sync Command

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/database-sync.mdx

Use the `preview-sync` command to verify the sync structure before performing the actual sync.

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

--------------------------------

### Markdown Frontmatter with ID

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Example of markdown frontmatter including an `id` field, which is required for clean sync operations to Notion databases.

```markdown
---
id: my-unique-page-id
title: My Document
---

Content here...
```

--------------------------------

### Initial Tree Building Logic

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/contributing/implementation-details.mdx

Iterates through sorted file paths to construct the initial sitemap tree structure. Requires a SiteMap instance and path module.

```typescript
for (const filepath of sortedFilePaths) {
  const parts = filepath.split(path.sep);
  let currentNode = siteMap._root;

  for (const part of parts) {
    // Create or find child nodes
    // Update parent-child relationships
  }
}
```

--------------------------------

### Setting Notion Page Icon in Frontmatter

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/writing/styling-notion-page.mdx

Example of the 'icon' property in frontmatter, used to set an emoji icon for the Notion page.

```markdown
icon: <emoji-unicode>
```

--------------------------------

### Setting Notion Page ID in Frontmatter

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/writing/styling-notion-page.mdx

Example of the 'id' property in frontmatter, used to store the Notion page ID for incremental updates.

```markdown
id: 12345678-1234-1234-1234-123456789abc
```

--------------------------------

### Markdown Frontmatter with Saved ID

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Example of markdown frontmatter after a sync operation with the `--save-id` option, showing the added `id` field with the Notion page ID.

```markdown
---
id: 12345678-1234-1234-1234-123456789abc
title: My Document
---

Content here...
```

--------------------------------

### Mk Notes CLI: Basic Sync

Source: https://context7.com/myastr0/mk-notes/llms.txt

Sync a local directory of Markdown files to a specified Notion page. This command creates a matching page hierarchy in Notion.

```bash
mk-notes sync \
  --input ./docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123xyz
```

--------------------------------

### Conditional Workflow Trigger

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/best-practices.mdx

Demonstrates conditional workflow triggers. The first example syncs only on pushes to the main branch. The second syncs only when specific files change. The third enables manual triggering.

```yaml
# Only sync on main branch pushes
if: github.ref == 'refs/heads/main'
```

```yaml
# Only sync when specific files change
on:
  push:
    paths: ['docs/**', 'README.md']
```

```yaml
# Manual sync with workflow_dispatch
on:
  workflow_dispatch:
```

--------------------------------

### Preview synchronization results

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/getting-started/1-your-first-synchronization.mdx

Run this command to visualize the Notion page architecture that will be generated from your markdown files without performing an actual sync.

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

--------------------------------

### CLI Options for Synchronization

Source: https://context7.com/myastr0/mk-notes/llms.txt

Lists the command-line interface options available for synchronization, including short and long flags for input path, destination, API key, and various sync behaviors.

```bash
// CLI equivalent options
// -i, --input <path>              Path to markdown file or directory
// -d, --destination <notionUrl>   Notion page or database URL
// -k, --notion-api-key <key>      Notion API secret token
// -c, --clean                     Clean sync mode
// -l, --lock                      Lock page after sync
// -s, --save-id                   Save page IDs to frontmatter
// -f, --force-new                 Force create new pages
// --flat                          Flatten page tree
// -v, --verbosity <level>         Log level (error|warn|info|debug)
```

--------------------------------

### Mk Notes CLI: Save Preview to File

Source: https://context7.com/myastr0/mk-notes/llms.txt

Execute a preview sync and save the output to a specified file. This allows for offline review or sharing of the planned Notion structure.

```bash
mk-notes preview-sync --input ./docs --output preview.txt
```

--------------------------------

### Markdown Frontmatter for Notion Database Property Mapping

Source: https://context7.com/myastr0/mk-notes/llms.txt

Map Markdown frontmatter properties to Notion database columns. This example demonstrates mapping various data types including Select, Multi-select, Number, Checkbox, URL, Email, and Date.

```markdown
---
title: API Authentication Guide
properties:
  - name: status
    value: published           # Maps to Select property
  - name: category
    value: API                 # Maps to Select property
  - name: tags
    value: "auth, security"    # Maps to Multi-select (comma-separated)
  - name: priority
    value: 1                   # Maps to Number property
  - name: is-featured
    value: true                # Maps to Checkbox property
  - name: docs-url
    value: "https://docs.example.com"  # Maps to URL property
  - name: author-email
    value: "dev@example.com"   # Maps to Email property
  - name: published-date
    value: "2024-01-15"        # Maps to Date property
---

# API Authentication Guide

This guide covers authentication methods for the API...
```

--------------------------------

### Mk Notes CLI: Preview Single File

Source: https://context7.com/myastr0/mk-notes/llms.txt

Generate a preview for a single Markdown file. This command shows how that specific file would be represented in Notion without affecting other files.

```bash
mk-notes preview-sync --input ./docs/README.md
```

--------------------------------

### Basic Preview Sync

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Previews the structure of markdown files as they would appear in Notion without performing synchronization. Use with a specified input path.

```bash
mk-notes preview-sync --input ./my-docs
```

--------------------------------

### GitHub Action for Preview Sync

Source: https://context7.com/myastr0/mk-notes/llms.txt

This workflow runs on pull requests that modify files in the 'docs' directory. It checks out the repository, uses the 'mk-notes/preview' action to generate a plain text preview of the documentation, and then uploads this preview as an artifact.

```yaml
name: Preview and Sync

on:
  pull_request:
    paths: ['docs/**']

jobs:
  preview-and-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Preview synchronization
        uses: Myastr0/mk-notes/preview
        with:
          input: './docs'
          format: 'plainText'
          output: './preview.txt'

      - name: Upload preview
        uses: actions/upload-artifact@v4
        with:
          name: sync-preview
          path: ./preview.txt
```

--------------------------------

### Sync with Flat Structure

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Synchronizes markdown files from a local directory to Notion, creating all pages as direct children of the destination page. Requires input directory, Notion destination URL, and API key.

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

--------------------------------

### Mk Notes CLI: Complete Reset Sync

Source: https://context7.com/myastr0/mk-notes/llms.txt

Perform a comprehensive sync reset by combining clean sync, forcing new pages, and saving IDs. This ensures a complete content replacement and prepares for future incremental updates.

```bash
mk-notes sync \
  --input ./docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123xyz \
  --clean --force-new --save-id
```

--------------------------------

### Run Linter

Source: https://github.com/myastr0/mk-notes/blob/master/CONTRIBUTING.md

Check code quality and style consistency by running the linter.

```sh
yarn lint
```

--------------------------------

### Sync Markdown to Notion Database

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/blog/2025-11-30-v3-database-support/index.mdx

Use the --destination flag with a Notion database URL to initiate synchronization.

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

--------------------------------

### Preview Sync in JSON Format

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Previews the structure of markdown files in JSON format. Specify the input path and set the format option to 'json'.

```bash
mk-notes preview-sync --input ./my-docs --format json
```

--------------------------------

### GitHub Actions: Complete Reset Workflow

Source: https://context7.com/myastr0/mk-notes/llms.txt

Automates a complete reset synchronization to Notion, including cleaning existing content, forcing new pages, and committing updated IDs.

```yaml
# Complete reset workflow
name: Reset Sync

on:
  workflow_dispatch:

jobs:
  reset-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Reset sync to Notion
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
          clean: 'true'
          force-new: 'true'
          save-id: 'true'

      - name: Commit new page IDs
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git add docs/
          git diff --staged --quiet || git commit -m "chore: reset Notion page IDs"
          git push
```

--------------------------------

### Preview Sync Command

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Allows users to preview the structure of their markdown files as they would appear in Notion before performing an actual synchronization.

```APIDOC
## POST /api/preview-sync

### Description
Previews the synchronization structure of markdown files without making any changes to Notion. Useful for verifying the hierarchy and content organization.

### Method
POST

### Endpoint
/api/preview-sync

### Parameters
#### Command Line Arguments
- **-i, --input** (string) - Required - Path to a markdown file or directory containing markdown files.
- **-f, --format** (string) - Optional - Output format for the preview. Options: `plainText` (default), `json`.
- **-o, --output** (string) - Optional - Path to save the preview output to a file.
- **--flat** (boolean) - Optional - Flattens the preview structure, simulating the behavior of the `--flat` option during sync.

### Request Example
1. Basic preview:
   ```bash
   mk-notes preview-sync --input ./my-docs
   ```
2. JSON format preview:
   ```bash
   mk-notes preview-sync --input ./my-docs --format json
   ```
3. Save preview to a file:
   ```bash
   mk-notes preview-sync --input ./my-docs --output preview.txt
   ```
4. Preview with flat structure:
   ```bash
   mk-notes preview-sync --input ./my-docs --flat
   ```

### Response
#### Success Response (200)
- **preview** (string or object) - The preview output, either as a plain text tree structure or a JSON object, depending on the `--format` option.

#### Response Example (plainText)
```
├─  (Your parent Notion Page)
│   ├─ getting-started.md
│   ├─ guides/
│   │   ├─ installation.md
│   │   ├─ configuration.md
│   │   ├─ api/
│   │   │   ├─ endpoints.md
│   │   │   ├─ authentication.md
```

#### Response Example (json)
```json
{
  "structure": [
    {
      "name": "getting-started.md",
      "children": []
    },
    {
      "name": "guides",
      "children": [
        {
          "name": "installation.md",
          "children": []
        },
        {
          "name": "configuration.md",
          "children": []
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Clone Mk Notes Repository

Source: https://github.com/myastr0/mk-notes/blob/master/CONTRIBUTING.md

Clone your forked repository to your local machine and navigate into the project directory.

```sh
git clone https://github.com/your-username/mk-notes.git
cd mk-notes
```

--------------------------------

### Myastr0/mk-notes/preview Action

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/1-preview-action.mdx

This GitHub Action previews the synchronization results of markdown files to Notion, helping verify structure before performing an actual sync.

```APIDOC
## GitHub Action: Myastr0/mk-notes/preview

### Description
The preview action shows you what the synchronization result will look like without actually performing the sync. This is useful for verifying the structure before making changes.

### Inputs
- **input** (string) - Required - The path to the markdown file or directory to synchronize.
- **format** (string) - Required - The format of the preview ("plainText" or "json").
- **output** (string) - Optional - The path to the output file.

### Outputs
- **file-path** (string) - The path to the output file (only set when output is specified).

### Request Example
```yaml
- name: Preview markdown synchronization
  uses: Myastr0/mk-notes/preview
  with:
    input: './docs'
    format: 'plainText'
    output: './preview.txt'
```
```

--------------------------------

### Sync Directory to a Notion Database

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Syncs all markdown files in a directory to a specified Notion database, creating new pages as database items. Requires the Notion API key.

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

--------------------------------

### Preview Synchronization

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/programmatic-usage.mdx

Preview how markdown files will be organized in Notion without making changes. Specify input path and desired format. Optionally save the preview to a file.

```typescript
const preview = await client.previewSynchronization({
  inputPath: './docs/',
  format: 'plainText', // or 'json'
  output: './preview.txt', // optional: save to file
});

console.log(preview);
```

```typescript
client
  .previewSynchronization({
    inputPath: './notes/',
    format: 'plainText',
  })
  .then(console.log);
```

--------------------------------

### Save Preview Sync to File

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Saves the preview of the markdown file structure to a specified output file. Use the '--output' option to designate the file path.

```bash
mk-notes preview-sync --input ./my-docs --output preview.txt
```

--------------------------------

### Preview Sync with Flat Structure

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Previews how markdown files will be organized in a flat structure in Notion, where all pages are direct children of the root. Use the '--flat' option with the '--input' path.

```bash
mk-notes preview-sync --input ./my-docs --flat
```

--------------------------------

### Synchronize markdown files to Notion

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/getting-started/1-your-first-synchronization.mdx

Execute the sync command to push markdown content to a Notion page or database. Requires a valid Notion API key and destination URL.

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

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

--------------------------------

### Run CLI Locally

Source: https://github.com/myastr0/mk-notes/blob/master/CONTRIBUTING.md

Execute the Mk Notes CLI locally by specifying the desired command.

```sh
yarn cli <command>
```

--------------------------------

### Preview Markdown Synchronization with GitHub Actions

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/first-synchronization.mdx

Use this workflow to preview the Notion page structure generated from your markdown files before automating the sync. It requires checkout and the preview action.

```yaml
name: Preview Sync

on:
  workflow_dispatch:

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Preview synchronization
        uses: Myastr0/mk-notes/preview
        with:
          input: './docs' # Path to your markdown files
          format: 'plainText'
```

--------------------------------

### Preview Single Markdown File

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Previews the structure for a single markdown file. Provide the path to the specific file using the '--input' option.

```bash
mk-notes preview-sync --input ./my-docs/README.md
```

--------------------------------

### Perform Idempotent Sync

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/blog/2025-11-30-v3-database-support/index.mdx

Use the --clean flag to update existing pages based on the mk-notes-id property instead of creating duplicates.

```bash
    mk-notes sync \
        --input ./docs \
        --destination <database-url> \
        --notion-api-key <api-key> \
        --clean
```

--------------------------------

### Sync with Flat Structure

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/database-sync.mdx

Use the `--flat` option to sync all pages as direct children of the database, useful for flat database views.

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

--------------------------------

### Configure page icons

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/writing/notion-limitations.mdx

Demonstrates supported emoji icons versus unsupported custom image files in frontmatter.

```markdown
---
icon: 💡  ✅ Supported
icon: 🚀  ✅ Supported
icon: custom-image.png  ❌ Not supported
---
```

--------------------------------

### Configure Clean Sync to Database

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

Use the clean option to synchronize markdown files with a Notion database.

```yaml
name: Clean Sync to Database

on:
  workflow_dispatch:

jobs:
  clean-sync-database:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Clean sync to Notion database
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DATABASE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
          clean: 'true'
```

--------------------------------

### GitHub Action for Weekly JSON Preview Generation

Source: https://context7.com/myastr0/mk-notes/llms.txt

This workflow is scheduled to run weekly to generate a JSON structure of the documentation. It checks out the repository, uses the 'mk-notes/preview' action to create a JSON output, and uploads it as a build artifact.

```yaml
# Generate JSON preview weekly
name: Generate JSON Preview

on:
  schedule:
    - cron: '0 0 * * 0'

jobs:
  generate-preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate JSON preview
        uses: Myastr0/mk-notes/preview
        with:
          input: './docs'
          format: 'json'
          output: './docs-structure.json'

      - name: Upload JSON preview
        uses: actions/upload-artifact@v4
        with:
          name: docs-structure
          path: ./docs-structure.json
```

--------------------------------

### Sync with Force New Option

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Syncs markdown files to Notion by creating new pages for all files, ignoring any existing page IDs in the frontmatter. This is useful for recreating pages.

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

--------------------------------

### previewSynchronization

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/programmatic-usage.mdx

Preview how markdown files will be organized in Notion without making any actual changes to the Notion workspace.

```APIDOC
## previewSynchronization

### Description
Preview how your markdown files will be organized in Notion without making any changes.

### Parameters
#### Request Body
- **inputPath** (string) - Required - Path to a markdown file or directory
- **format** ('plainText' | 'json') - Required - Output format for the preview
- **output** (string) - Optional - Path to save the preview output

### Request Example
{
  "inputPath": "./docs/",
  "format": "plainText",
  "output": "./preview.txt"
}
```

--------------------------------

### Sync a Single File to Notion

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Use this command to sync a single markdown file to a specific Notion page. It converts and uploads the content, then displays the Notion page URL.

```bash
mk-notes sync \
  --input ./my-docs/README.md \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123...
```

--------------------------------

### Sync with Flat Structure

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

Use the flat option to ignore folder hierarchy and create a flat list of pages in Notion.

```yaml
name: Flat Sync

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  flat-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync with flat structure
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
          flat: 'true'
```

--------------------------------

### Configure Preview Action in Workflow

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/1-preview-action.mdx

Basic configuration for the preview action within a GitHub Actions workflow step.

```yaml
steps:
  - name: Checkout repository
    uses: actions/checkout@v4

  - name: Preview markdown synchronization
    uses: Myastr0/mk-notes/preview
    with:
      input: './docs' # The path to the markdown file or directory to preview
      format: 'plainText' # The format of the preview ("plainText" or "json")
      output: './preview.txt' # Optional: path to save the preview
```

--------------------------------

### Mk Notes CLI: Sync to Notion Database

Source: https://context7.com/myastr0/mk-notes/llms.txt

Sync Markdown files to a Notion database. This command is similar to syncing to a page but targets a database as the destination, preserving incremental updates.

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

--------------------------------

### GitHub Actions: Basic Sync to Notion

Source: https://context7.com/myastr0/mk-notes/llms.txt

Automates Markdown to Notion synchronization on push events to the main branch, triggered by changes in the 'docs' directory.

```yaml
# .github/workflows/sync-to-notion.yml
name: Sync to Notion

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync to Notion
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs'
          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

--------------------------------

### GitHub Actions: Preview and Sync

Source: https://context7.com/myastr0/mk-notes/llms.txt

Configuration for the GitHub Action to preview and sync documentation changes.

```APIDOC
## GitHub Action: Preview and Sync

### Description
This workflow triggers on pull requests to the docs directory, generating a plain text preview of the documentation and uploading it as an artifact.

### Parameters
#### Request Body (Action Inputs)
- **input** (string) - Required - Path to the documentation directory (e.g., './docs')
- **format** (string) - Required - Output format (e.g., 'plainText')
- **output** (string) - Required - Path to the output file (e.g., './preview.txt')
```

--------------------------------

### Mk Notes CLI: Sync with Incremental Updates

Source: https://context7.com/myastr0/mk-notes/llms.txt

Perform a sync operation while enabling incremental updates. Page IDs are saved to the Markdown frontmatter, allowing for efficient updates of existing Notion pages.

```bash
mk-notes sync \
  --input ./docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123xyz \
  --save-id
```

--------------------------------

### synchronizeMarkdownToNotionFromFileSystem

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/programmatic-usage.mdx

Synchronize markdown files from the local file system to a Notion page or database.

```APIDOC
## synchronizeMarkdownToNotionFromFileSystem

### Description
Synchronize markdown files to a Notion page or database.

### Parameters
#### Request Body
- **inputPath** (string) - Required - Path to a markdown file or directory
- **parentNotionPageId** (string) - Required - URL of the Notion page or database
- **cleanSync** (boolean) - Optional - Remove existing content before syncing (Default: false)
- **lockPage** (boolean) - Optional - Lock the Notion page after syncing (Default: false)
- **saveId** (boolean) - Optional - Save Notion page IDs back to markdown frontmatter (Default: false)
- **forceNew** (boolean) - Optional - Force creation of new pages, ignoring existing IDs (Default: false)

### Request Example
{
  "inputPath": "./docs/",
  "parentNotionPageId": "https://notion.so/myworkspace/page-123456",
  "cleanSync": false,
  "lockPage": false,
  "saveId": true,
  "forceNew": false
}
```

--------------------------------

### Automate Markdown to Notion Synchronization with GitHub Actions

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/first-synchronization.mdx

Automate markdown file synchronization to Notion by setting up this GitHub workflow. It triggers on pushes to the main branch affecting the 'docs/' directory and requires your Notion API key as a secret.

```yaml
name: Sync to Notion

on:
  push:
    branches: [main]
    paths: ['docs/**'] # Only trigger when docs change

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Sync to Notion
        uses: Myastr0/mk-notes/sync
        with:
          input: './docs' # Path to your markdown files
          destination: <your-notion-page-or-database-url>
          notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

--------------------------------

### Sync Directory with Clean and Lock Options

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Performs a clean sync of a directory to Notion, removing all existing content from the destination page before syncing. The `--lock` option prevents further editing.

```bash
mk-notes sync \
  --input ./my-docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123... \
  --clean \
  --lock
```

--------------------------------

### Basic Sync Action Usage

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/github-actions/available-actions/2-sync-action.mdx

Use this snippet to synchronize markdown files to a Notion page or database. Ensure you provide the input path, destination URL, and your Notion API key as a secret.

```yaml
steps:
  - name: Checkout repository
    uses: actions/checkout@v4

  - name: Sync markdown to Notion
    uses: Myastr0/mk-notes/sync
    with:
      input: './docs' # The path to the markdown file or directory to synchronize
      destination: 'https://notion.so/your-page-or-database-id'
      notion-api-key: ${{ secrets.NOTION_API_KEY }}
```

--------------------------------

### Sync Directory of Markdown Files

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Synchronizes an entire directory of markdown files to Notion, preserving the directory structure. Specify the input directory, Notion destination URL, and API key.

```bash
mk-notes sync -i ./docs -d <notion-url> -k <api-key>
```

--------------------------------

### Mk Notes CLI: Flat Structure Sync

Source: https://context7.com/myastr0/mk-notes/llms.txt

Sync Markdown files to Notion using a flat structure. All synced pages will appear as direct children of the destination page, without replicating the directory hierarchy.

```bash
mk-notes sync \
  --input ./docs \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123xyz \
  --flat
```

--------------------------------

### Single File vs Directory Synchronization

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Explains how Mk Notes handles synchronization for both individual markdown files and entire directories.

```APIDOC
## POST /api/sync (File vs Directory Handling)

### Description
Details the behavior of the `mk-notes sync` command when the input is either a single markdown file or a directory.

### Method
POST

### Endpoint
/api/sync

### Parameters
#### Command Line Arguments
- **-i, --input** (string) - Required - Path to a single `.md` file or a directory containing markdown files.
- **-d, --destination** (string) - Required - The URL of the Notion page to sync to.
- **-k, --api-key** (string) - Required - Your Notion API key.

### Behavior
#### Single File Synchronization
- **Input**: A path to a single `.md` file.
- **Behavior**: Creates a single Notion page with the content of the specified markdown file.
- **Use Case**: Syncing a standalone document.
- **Example**: `mk-notes sync -i ./docs/README.md -d <notion-url> -k <api-key>`

#### Directory Synchronization
- **Input**: A path to a directory containing markdown files.
- **Behavior**: Creates a hierarchical structure in Notion that mirrors the directory structure of the input path.
- **Use Case**: Syncing a complete documentation project.
- **Example**: `mk-notes sync -i ./docs -d <notion-url> -k <api-key>`

### Error Handling
- **Non-markdown file**: An error message is displayed if a non-markdown file is provided as input.
- **Non-existent path**: A clear error message is shown if the provided input path does not exist.
- **Supported files**: Only `.md` files are supported for synchronization.
```

--------------------------------

### Sync Markdown to Notion Database

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/database-sync.mdx

Commands for synchronizing markdown files to a Notion database with various configuration flags.

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

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

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

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

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

--------------------------------

### Sync Database with Clean Option

Source: https://github.com/myastr0/mk-notes/blob/master/docs/content/docs/cli/guides/cli-commands.mdx

Performs a clean sync to a Notion database, deleting existing content before syncing new pages. Markdown files must include an `id` in their frontmatter for this operation.

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

--------------------------------

### Mk Notes CLI: Sync Single File

Source: https://context7.com/myastr0/mk-notes/llms.txt

Sync a single Markdown file to a specified Notion page. This is useful for updating individual documents without affecting the rest of the hierarchy.

```bash
mk-notes sync \
  --input ./docs/README.md \
  --destination https://notion.so/myworkspace/doc-123456 \
  --notion-api-key secret_abc123xyz
```