### Mk Notes CLI Sync - Directory Example

Source: https://mk-notes.io/docs/cli/guides/cli-commands

This example demonstrates how to use the `mk-notes sync` command to synchronize an entire directory of markdown files to a Notion page. It specifies the input directory, Notion destination URL, and the Notion API key for authentication.

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

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

### Mk Notes CLI Sync - Single File Example

Source: https://mk-notes.io/docs/cli/guides/cli-commands

This example illustrates how to use the `mk-notes sync` command to synchronize a single markdown file to a Notion page. It specifies the input file path, Notion destination URL, and the Notion API key.

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

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

### Complete Markdown File Example with Sync Data

Source: https://mk-notes.io/docs/cli/guides/database-sync

An example of a fully synced markdown file, including Notion-specific frontmatter like id, title, icon, and custom properties. The 'id' is auto-generated when using --save-id.

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

```

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

### Install Mk Notes using npm

Source: https://mk-notes.io/docs/cli/guides/programmatic-usage

This command installs the Mk Notes library. It is a prerequisite for using the library programmatically in your project.

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

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

### Sync Documentation on Release

Source: https://mk-notes.io/docs/github-actions/available-actions/2-sync-action

This example shows how to automatically sync documentation to Notion whenever a new release is published. It utilizes GitHub Actions triggers for releases and requires checkout, sync action, and secret configuration.

```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 }}
```

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

### Preview Sync Structure

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command allows you to preview the structure and content that will be synced to Notion without actually performing the sync. It's useful for verifying changes before committing them.

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

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

### Clean Sync to Notion Database

Source: https://mk-notes.io/docs/github-actions/available-actions/2-sync-action

This example demonstrates a clean sync to a Notion database, ensuring all previous content is removed before the new sync. It requires markdown files to have an `id` in their frontmatter for proper handling. Triggered manually via workflow_dispatch.

```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'
```

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

### Preview Markdown Sync with GitHub Actions

Source: https://mk-notes.io/docs/github-actions/first-synchronization

This GitHub Actions workflow allows you to preview the synchronization result of your markdown files to Notion without actually performing the sync. It uses the `actions/checkout` action to get your repository code and the `Myastr0/mk-notes/preview` action to generate a preview of the Notion page structure. The `input` parameter specifies the path to your markdown files, and `format` can be set to 'plainText' or other supported formats.

```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'
```

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

### Basic Sync Command with Save ID

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command syncs markdown files while enabling incremental updates by saving Notion page IDs to the frontmatter. This prevents duplicate page creation.

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

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

### Mk Notes CLI Sync - Directory with Clean Sync

Source: https://mk-notes.io/docs/cli/guides/cli-commands

This example shows the `mk-notes sync` command with the `--clean` option, which removes all existing content from the destination Notion page before syncing. This is useful for a complete overwrite but should be used with caution.

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

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

### Generate JSON Preview of Markdown Structure (GitHub Actions)

Source: https://mk-notes.io/docs/github-actions/available-actions/1-preview-action

This example shows how to generate a JSON preview of your markdown synchronization structure using the Mk Notes preview action. It's configured to run on a schedule and saves the JSON output as a GitHub artifact, which is beneficial for automated analysis and integration.

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

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

### Notion API Icon Support Example

Source: https://mk-notes.io/docs/writing/notion-limitations

Demonstrates the supported and unsupported icon formats for Notion pages via the API. Only general emojis are supported; custom images are not.

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

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

### Full Reset Sync Command

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command performs a complete reset by deleting all existing pages in the Notion database and recreating them from the local markdown files. It ensures all new page IDs are saved.

```bash
mk-notes sync --clean --force-new --save-id
```

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

### Adding Custom Notion Database Properties via Frontmatter

Source: https://mk-notes.io/docs/cli/guides/database-sync

Demonstrates how to define custom database properties (like status, category, priority) directly within the markdown file's frontmatter. MK Notes maps these to existing Notion properties.

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

Your content here...
```

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

### Clean Sync to Notion

Source: https://mk-notes.io/docs/github-actions/available-actions/2-sync-action

This example utilizes the 'clean' option to remove all existing content from the Notion destination before syncing new markdown files. It is triggered manually via workflow_dispatch and requires checkout, sync action, and secrets.

```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'
```

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

### MK Notes Basic Database Sync Command

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command initiates a basic synchronization of markdown files from a local directory to a specified Notion database. Without additional flags, running this command multiple times will result in duplicate entries in the Notion database.

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

```

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

### Block Equation Example (Markdown)

Source: https://mk-notes.io/docs/writing/using-equations

Shows how to render a complex mathematical equation on its own line using double dollar signs for LaTeX. This is suitable for displaying standalone mathematical expressions.

```markdown
$$ 
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} 
$$
```

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

### Inline Equation Example (Markdown)

Source: https://mk-notes.io/docs/writing/using-equations

Demonstrates how to embed a simple inline equation within a text line using single dollar signs for LaTeX. This requires the mk-notes processor to interpret the LaTeX syntax.

```markdown
Here is a sentence with an inline equation: $E = mc^2$.
```

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

### MK Notes Combined Clean and Force New Sync

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command combines the '--clean' and '--force-new' flags to delete all existing content in the destination database and then create new pages for all synced markdown files. This effectively replaces all content with a fresh import.

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

```

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

### Sync Notion Database with Flat Structure

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command syncs local markdown files to a Notion database, flattening the page hierarchy. The --flat option ensures all pages are direct children of the database, simplifying filtering and sorting.

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

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

### MK Notes Force New Pages Command

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command forces MK Notes to create new pages in the Notion database, ignoring any previously stored page IDs in the markdown frontmatter. It is useful for creating fresh copies or testing synchronization without affecting existing content.

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

```

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

### SiteMap Initial Tree Building Process

Source: https://mk-notes.io/docs/contributing/implementation-details

Demonstrates the initial phase of constructing the sitemap tree by iterating through sorted file paths and progressively building the tree structure. It involves creating or finding child nodes and updating parent-child relationships.

```javascript
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
  }
}
```

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

### Preview and Sync to Notion with Mk Notes Action

Source: https://mk-notes.io/docs/github-actions/best-practices

Demonstrates using the Mk Notes preview action before syncing to Notion. It ensures the structure is verified before the main sync occurs. The preview action takes an input directory and format, while the sync action requires input, destination, and Notion API key.

```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 }}
```

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

### Markdown Frontmatter for Mk Notes

Source: https://mk-notes.io/docs/writing/styling-notion-page

Example of markdown frontmatter structure used by Mk Notes to define metadata for Notion pages. This includes properties like id, title, and icon.

```markdown
# Beginning of your markdown file

---

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

---
```

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

### Preview Markdown Synchronization with Mk Notes CLI

Source: https://mk-notes.io/docs/cli/getting-started/1-your-first-synchronization

This command allows you to preview the Notion page structure that will be generated from your markdown files before performing an actual synchronization. It takes the path to your markdown files or directory as input.

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

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

### Syncing with Force New (Recreate Pages)

Source: https://mk-notes.io/docs/cli/guides/cli-commands

Synchronizes markdown files to Notion by creating new pages for all files, ignoring any existing page IDs in the frontmatter. This is useful for forcing a complete recreation of pages in Notion.

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

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

### Supported List Nesting Structure (Max 3 Levels)

Source: https://mk-notes.io/docs/writing/notion-limitations

Example of a markdown list structure that adheres to Notion API's maximum supported nesting depth of 3 levels for bulleted and numbered lists.

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

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

### Problematic List Nesting Structure (Exceeds 3 Levels)

Source: https://mk-notes.io/docs/writing/notion-limitations

Example of a markdown list structure that will cause a validation error in Notion API due to exceeding the maximum allowed nesting depth of 3 levels.

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

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

### Preview and Sync Workflow (GitHub Actions)

Source: https://mk-notes.io/docs/github-actions/available-actions/1-preview-action

This GitHub Actions workflow demonstrates a common pattern: previewing markdown synchronization before performing an actual sync. It checks out the code, previews the synchronization, uploads the preview as an artifact, and then conditionally syncs to Notion on push events. It uses the 'preview' and 'sync' actions from the mk-notes project.

```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 }}
```

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

### MkNotes Constructor

Source: https://mk-notes.io/docs/cli/guides/programmatic-usage

Initialize the MkNotes client with necessary options.

```APIDOC
## Constructor Options

| Option        | Type                                  | Description                                  | Default |
|---------------|---------------------------------------|----------------------------------------------|---------|
| `notionApiKey`  | `string`                              | Your Notion API secret token (required)      | -       |
| `LOG_LEVEL`     | `'error' | 'warn' | 'info' | 'debug'` | Log level for the client                   | `'error'` |
| `logger`        | `winston.Logger`                      | Custom Winston logger instance               | -       |

### Request Example
```javascript
import MkNotes from 'mk-notes';

const client = new MkNotes({
  notionApiKey: process.env.NOTION_API_KEY,
  LOG_LEVEL: 'info',
});
```
```

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

### previewSynchronization

Source: https://mk-notes.io/docs/cli/guides/programmatic-usage

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

```APIDOC
## `previewSynchronization`

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

### Method
`previewSynchronization(options)`

### Parameters

| Parameter   | Type                                  | Description                           | Required |
|-------------|---------------------------------------|---------------------------------------|----------|
| `inputPath` | `string`                              | Path to a markdown file or directory  | Yes      |
| `format`    | `'plainText' | 'json'`                  | Output format for the preview         | Yes      |
| `output`    | `string`                              | Path to save the preview output       | No       |

### Request Example
```javascript
const preview = await client.previewSynchronization({
  inputPath: './docs/',
  format: 'plainText',
  output: './preview.txt', // optional: save to file
});

console.log(preview);
```

### Response Example
```json
{
  "message": "Preview generated successfully."
}
```
```

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

### Markdown Frontmatter with Notion Page ID

Source: https://mk-notes.io/docs/cli/guides/database-sync

Demonstrates the structure of a markdown file's frontmatter when the 'id' property is used to store the Notion page ID. This property is automatically populated when using the '--save-id' option during synchronization.

```markdown
---\nid: 12345678-1234-1234-1234-123456789abc
title: My Document Title
---

Your content here...

```

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

### Syncing to a Database with Clean Sync

Source: https://mk-notes.io/docs/cli/guides/cli-commands

Performs a clean sync to a Notion database, deleting existing content before adding new markdown files as database items. Requires markdown files to have an `id` in their frontmatter for proper handling.

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

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

Content here...

```

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

### Preview Synchronization with MkNotes (Javascript/Typescript)

Source: https://mk-notes.io/docs/cli/guides/programmatic-usage

Shows how to use the `previewSynchronization` method to see how markdown files will be organized in Notion without making actual changes. It requires an input path and a format, and can optionally save the preview to a file.

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

console.log(preview);
```

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

### MK Notes Clean Sync Command

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command performs a clean synchronization by deleting all existing content in the destination Notion database before syncing new markdown files. Use this command with caution as it will permanently remove existing data.

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

```

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

### Automate Markdown to Notion Sync with GitHub Actions

Source: https://mk-notes.io/docs/github-actions/first-synchronization

This GitHub Actions workflow automates the synchronization of markdown files to Notion. It triggers on pushes to the `main` branch that modify files within the `docs/` directory. The workflow checks out the repository, then uses the `Myastr0/mk-notes/sync` action to perform the synchronization. Key inputs include `input` for the markdown file path, `destination` for the Notion page or database URL, and `notion-api-key` which should be configured as a GitHub 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 }}
```

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

### Preview Markdown File Organization with mk-notes preview-sync

Source: https://mk-notes.io/docs/cli/guides/cli-commands

The 'preview-sync' command allows users to visualize the hierarchical structure of their markdown files as they would appear in Notion before executing an actual synchronization. It supports different output formats like plain text (tree structure) and JSON, and can save the preview to a file. This is crucial for verifying the intended organization and avoiding unintended changes.

```bash
mk-notes preview-sync -i <path> [options]
```

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

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

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

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

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

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

### Preview Markdown Synchronization (GitHub Actions)

Source: https://mk-notes.io/docs/github-actions/available-actions/1-preview-action

This snippet demonstrates how to use the Mk Notes preview action within a GitHub Actions workflow. It checks out the repository, runs the preview action with specified input and format, and optionally saves the output to a file. It's useful for verifying synchronization results before actual syncing.

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

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

### Notion API List Nesting Error Example

Source: https://mk-notes.io/docs/writing/notion-limitations

Illustrates the validation error encountered when attempting to sync markdown content with more than 3 levels of list nesting in Notion API. This error indicates that the structure exceeds the allowed depth for bulleted or numbered lists.

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

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

### Syncing with Clean and Lock Options

Source: https://mk-notes.io/docs/cli/guides/cli-commands

Performs a clean sync by removing all existing content from the destination Notion page before synchronizing new markdown files. The destination page is then locked. This is useful for resetting content or ensuring a clean slate.

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

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

### Workaround: Using Callouts for Complex Hierarchies

Source: https://mk-notes.io/docs/writing/notion-limitations

Shows how to use Notion callouts as a workaround for organizing complex hierarchical content, especially when deeper nesting than allowed by lists is required. This example uses a callout to add details without creating another list level.

```markdown
- Level 1
  - Level 2

> **Note**: Additional details can be placed in callouts
```

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

### Synchronize Markdown Files to Notion using Mk Notes CLI

Source: https://mk-notes.io/docs/cli/getting-started/1-your-first-synchronization

This command synchronizes your markdown files to a specified Notion page or database. It requires the input path for markdown files, the Notion destination URL, and your Notion API key. It supports both Notion Pages and Databases as destinations.

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

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

### MK Notes Incremental Sync with --save-id

Source: https://mk-notes.io/docs/cli/guides/database-sync

This command enables incremental synchronization by saving the Notion page ID to the markdown file's frontmatter after a successful sync. Subsequent runs will update existing pages instead of creating duplicates, making it the recommended approach for managing content.

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

```

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

### Basic Sync Action Usage

Source: https://mk-notes.io/docs/github-actions/available-actions/2-sync-action

This snippet demonstrates the basic usage of the sync action to synchronize markdown files from a local directory to a Notion page or database. It requires the input path, destination URL, and your Notion API key.

```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 }}
```

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

### synchronizeMarkdownToNotionFromFileSystem

Source: https://mk-notes.io/docs/cli/guides/programmatic-usage

Synchronize markdown files to a Notion page or database.

```APIDOC
## `synchronizeMarkdownToNotionFromFileSystem`

Synchronize markdown files to a Notion page or database.

### Method
`synchronizeMarkdownToNotionFromFileSystem(options)`

### Parameters

| Parameter            | Type     | Description                                   | Default |
|----------------------|----------|-----------------------------------------------|---------|
| `inputPath`          | `string` | Path to a markdown file or directory          | Required|
| `parentNotionPageId` | `string` | URL of the Notion page or database            | Required|
| `cleanSync`          | `boolean`| Remove existing content before syncing         | `false` |
| `lockPage`           | `boolean`| Lock the Notion page after syncing            | `false` |
| `saveId`             | `boolean`| Save Notion page IDs back to markdown frontmatter | `false` |
| `forceNew`           | `boolean`| Force creation of new pages, ignoring existing IDs | `false` |

### Request Example (Basic Sync)
```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
});
```

### Request Example (Sync with Incremental Updates)
```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
  saveId: true,
});
```

### Request Example (Clean Sync with Locking)
```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
  cleanSync: true,
  lockPage: true,
});
```

### Request Example (Force New Pages)
```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
  forceNew: true,
  saveId: true, // Save the new page IDs
});
```

### Request Example (Complete Reset)
```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
  cleanSync: true, // Delete existing content
  forceNew: true, // Ignore existing IDs
  saveId: true, // Save new IDs
});
```

### Response Example
```json
{
  "message": "Synchronization complete."
}
```
```

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

### Initialize MkNotes Client (Javascript/Typescript)

Source: https://mk-notes.io/docs/cli/guides/programmatic-usage

Demonstrates how to import and initialize the MkNotes client with a Notion API key. The client instance is used to interact with Mk Notes functionalities. Constructor options like LOG_LEVEL can also be set.

```javascript
import MkNotes from 'mk-notes';

const client = new MkNotes({
  notionApiKey: 'YOUR_NOTION_SECRET',
});
```

```javascript
import MkNotes from 'mk-notes';

const client = new MkNotes({
  notionApiKey: process.env.NOTION_API_KEY,
  LOG_LEVEL: 'info',
});
```

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

### Syncing to a Notion Database

Source: https://mk-notes.io/docs/cli/guides/cli-commands

Synchronizes markdown files to a specified Notion database. Each markdown file will be created as a separate item within the database. This is ideal for managing structured content in Notion.

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

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

### Sync on Push to Main Branch

Source: https://mk-notes.io/docs/github-actions/available-actions/2-sync-action

This configuration demonstrates syncing content to Notion automatically on every push to the main branch, specifically targeting files within the 'docs' directory. It includes checkout, the sync action, and secret management.

```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 }}
```

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

### Syncing with Flat Structure

Source: https://mk-notes.io/docs/cli/guides/cli-commands

Synchronizes markdown files to a Notion page while flattening the directory structure. All markdown files are created as direct children of the destination page, simplifying navigation. The root node (e.g., index.md) is treated as a child page.

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

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

### Test Mk Notes CLI Locally

Source: https://mk-notes.io/docs/github-actions/troubleshooting

Run Mk Notes commands locally to test your configuration and preview synchronization before deploying to GitHub Actions. This helps in debugging issues related to input paths, formats, and sync destinations.

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

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

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

### Syncing with Save ID (Incremental Updates)

Source: https://mk-notes.io/docs/cli/guides/cli-commands

Synchronizes markdown files to Notion and saves the corresponding Notion page IDs back into the markdown frontmatter. Subsequent syncs will update existing pages rather than creating duplicates.

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

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

Content here...

```

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

### Preview Action

Source: https://mk-notes.io/docs/github-actions/available-actions/1-preview-action

This action allows you to preview markdown synchronization results without actually performing the sync. It helps in verifying the structure and content before making any actual changes.

```APIDOC
## Preview Action

### Description
Preview markdown synchronization results without actually syncing.

### Method
Uses GitHub Action

### Endpoint
Myastr0/mk-notes/preview

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

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

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

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

#### Response Example
```json
{
  "file-path": "./preview.txt"
}
```

### Preview Formats
#### Plain Text Format
The `plainText` format provides a human-readable representation of how your content will appear in Notion, showing the structure and hierarchy.

#### JSON Format
The `json` format provides a structured representation of your content, useful for automated processing, integration with other tools, and detailed analysis of content structure.
```

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

### Combining Force New, Clean, and Save ID

Source: https://mk-notes.io/docs/cli/guides/cli-commands

Performs a comprehensive sync by cleaning the destination, forcing new page creation (ignoring existing IDs), and then saving the new page IDs back to the markdown files. This effectively resets and resynchronizes all content.

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

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

### Syncing with Page Locking

Source: https://mk-notes.io/docs/cli/guides/cli-commands

Synchronizes markdown files to a Notion page and locks the page to prevent further edits. Reads markdown files from a specified input directory and syncs them to a Notion destination URL using an API key.

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

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

### Enable Incremental Updates for Mk Notes Synchronization

Source: https://mk-notes.io/docs/cli/getting-started/1-your-first-synchronization

This command synchronizes markdown files to Notion and enables incremental updates by saving Notion page IDs back to the markdown files. This prevents duplicate page creation on subsequent syncs by allowing Mk Notes to update existing pages. It requires input path, Notion destination URL, Notion API key, and the --save-id flag.

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

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

### CLI Command: sync

Source: https://mk-notes.io/docs/cli/guides/cli-commands

The `sync` command synchronizes markdown files to a Notion page or database. It supports syncing single files or entire directories, maintaining a page hierarchy.

```APIDOC
## `sync` Command

### Description
The `sync` command synchronizes markdown files to a Notion page or database. You can sync either a single markdown file or an entire directory of markdown files, creating a matching page hierarchy for directories.

### Method
CLI Command

### Endpoint
N/A (CLI Command)

### Parameters
#### Required Options
- **-i, --input <path>** (string) - Required - Path to a markdown file or directory containing your markdown files
- **-d, --destination <notionUrl>** (string) - Required - URL of the parent Notion page or database where content will be synchronized
- **-k, --notion-api-key <notionApiKey>** (string) - Required - Your Notion API key for authentication

#### Optional Options
- **-c, --clean** (boolean) - Optional - Clean sync mode. Removes all existing content from the destination page or database before syncing.
- **-l, --lock** (boolean) - Optional - Lock the Notion page after syncing to prevent further editing.
- **-s, --save-id** (boolean) - Optional - Save the Notion page ID back to your markdown file's frontmatter after synchronization for incremental updates.
- **-f, --force-new** (boolean) - Optional - Force creation of new pages even if your markdown files contain existing page IDs.
- **--flat** (boolean) - Optional - Flatten the result page tree, making all pages direct children of the destination instead of maintaining nested folder structures.

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

### Response
#### Success Response
- **message** (string) - Confirmation message indicating successful synchronization.
- **url** (string) - The URL of the synchronized Notion page or database.

#### Response Example
```json
{
  "message": "Synchronization successful!",
  "url": "https://notion.so/myworkspace/doc-123456"
}
```

#### Error Handling
- **Invalid input path**: Error message indicating the input path does not exist.
- **Invalid destination URL**: Error message indicating the Notion URL is malformed or invalid.
- **Authentication failed**: Error message indicating the Notion API key is invalid or lacks necessary permissions.
- **Sync failed**: Generic error message for other synchronization issues.
```

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

### Sync Notion with Flat Structure

Source: https://mk-notes.io/docs/github-actions/available-actions/2-sync-action

Synchronizes markdown files to Notion using a flat structure, ignoring folder hierarchy. All pages become direct children of the destination page, and the root node is skipped. Ideal for simple document lists or database syncing.

```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'

```

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

### SiteMap Serialization and Deserialization

Source: https://mk-notes.io/docs/contributing/implementation-details

Shows how the sitemap can be serialized into JSON format for persistence or debugging, and how it can be reconstructed back into a SiteMap object from its JSON representation.

```javascript
// Serialize to JSON
const json = siteMap.toJSON();

// Reconstruct from JSON
const reconstructed = SiteMap.fromJSON(json);
```

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

### Sync Action Usage

Source: https://mk-notes.io/docs/github-actions/available-actions/2-sync-action

Synchronize markdown files to Notion pages or databases.

```APIDOC
## POST /sync

### Description
Synchronizes markdown files to a Notion page or database, preserving structure and formatting.

### 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) - Optional - Clean sync mode - removes ALL existing content from the destination before syncing. Default: `false`.
- **lock** (boolean) - Optional - Lock the Notion page after syncing. Default: `false`.
- **save-id** (boolean) - Optional - Save Notion page IDs back to the source markdown files' frontmatter, enabling incremental updates on subsequent syncs. Default: `false`.
- **force-new** (boolean) - Optional - Force creation of new pages, ignoring any existing page IDs in the markdown frontmatter. Default: `false`.
- **flat** (boolean) - Optional - Flatten the result page tree, making all pages direct children of the destination instead of maintaining nested structures. Default: `false`.

### Request Example
```json
{
  "input": "./docs",
  "destination": "https://notion.so/your-page-or-database-id",
  "notion-api-key": "YOUR_NOTION_API_KEY",
  "clean": false,
  "lock": false,
  "save-id": false,
  "force-new": false,
  "flat": false
}
```

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

#### Response Example
```json
{
  "message": "Sync completed successfully."
}
```
```

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

### Sync with Force New for Recreating Pages in mk-notes sync

Source: https://mk-notes.io/docs/cli/guides/cli-commands

This command forces the creation of new Notion pages for all markdown files, even if pages with the same content already exist. This is useful for ensuring a fresh import or when dealing with potential synchronization conflicts.

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

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

### Sync to Notion Database

Source: https://mk-notes.io/docs/github-actions/available-actions/2-sync-action

This snippet shows how to sync markdown files to a Notion database, leveraging Notion's database features. It is configured to run on pushes to the main branch that affect the 'docs' directory and requires checkout, sync action, and 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 }}
```

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

### Synchronize Markdown to Notion with MkNotes (Javascript/Typescript)

Source: https://mk-notes.io/docs/cli/guides/programmatic-usage

Demonstrates the `synchronizeMarkdownToNotionFromFileSystem` method to sync markdown files to a Notion page or database. It requires an input path and the parent Notion page ID. Options like `cleanSync`, `lockPage`, `saveId`, and `forceNew` can be used to control the synchronization behavior.

```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: 'https://notion.so/myworkspace/page-123456',
  cleanSync: false,
  lockPage: false,
  saveId: true,
  forceNew: false,
});
```

```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
});
```

```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
  saveId: true,
});
```

```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
  cleanSync: true,
  lockPage: true,
});
```

```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
  forceNew: true,
  saveId: true, // Save the new page IDs
});
```

```javascript
await client.synchronizeMarkdownToNotionFromFileSystem({
  inputPath: './docs/',
  parentNotionPageId: process.env.NOTION_PAGE_URL,
  cleanSync: true, // Delete existing content
  forceNew: true, // Ignore existing IDs
  saveId: true, // Save new IDs
});
```

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

### Sync Markdown Files to a Notion Database with mk-notes sync

Source: https://mk-notes.io/docs/cli/guides/cli-commands

This command synchronizes markdown files, mapping them to properties within a specified Notion database. It requires the input path, Notion database URL, and API key.

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

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

### Sync to a Database with Clean Sync in mk-notes sync

Source: https://mk-notes.io/docs/cli/guides/cli-commands

This command synchronizes markdown files to a Notion database, first clearing all existing entries in the database before importing the new content.

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