Sync Action

Synchronize markdown files to Notion pages or databases using the sync GitHub Action

The sync action synchronizes your markdown files to a dedicated Notion page or database, maintaining the structure and formatting of your content.

Usage

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

Secret management

Please note that you should not commit your Notion API key to your repository. You should use a GitHub Secret to store your Notion API key. You can find more information in the Setting Up Secrets guide.

Inputs

Input	Description	Required	Default
`input`	The path to the markdown file or directory to synchronize	`true`	-
`destination`	The Notion page or database URL where you want to synchronize your markdown files	`true`	-
`notion-api-key`	Your Notion secret token	`true`	-
`clean`	Clean sync mode - For pages: removes ALL existing content. For databases: deletes pages with matching `mk-notes-id` before syncing	`false`	`false`
`lock`	Lock the Notion page after syncing	`false`	`false`

Destination Types

Notion Page

When the destination is a Notion page, content is appended directly to the page. Child pages are created as sub-pages.

Notion Database

When the destination is a Notion database, pages are created as database items. This is useful for managing collections of documents where you want to leverage Notion's database features.

Outputs

This action does not produce any outputs.

Examples

Sync Documentation on Release

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

Sync on Push to Main Branch

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

Clean Sync with Warning

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'

Sync to a Notion Database

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 Database with Clean Mode

When using clean sync with a database, make sure your markdown files include an id in the frontmatter:

---
id: my-unique-doc-id
title: My Document
---

Content here...

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'

Important Notes

For pages: The clean option removes ALL existing content from the destination page
For databases: The clean option deletes pages with matching mk-notes-id property before syncing
Use clean sync only when you're sure you want to replace content
Always test with the preview action first
Make sure your Notion integration has access to the target page or database

On this page