Frank Chen

Collecting stories by foot, lens, and occasional propeller

← Back to Posts

Sync posts from Notion

This article shows how blog posts can be synchronised between a GitHub repository and a Notion database. The idea is simple: write posts either locally in Markdown or directly inside Notion, while keeping both sides in sync. The workflow relies on a Notion integration and two GitHub Actions that handle synchronisation in both directions.

Thoughts 9 Mar 2026

Overview

The system uses two automated workflows.

  1. Repository → Notion When posts are pushed to the repository, a GitHub Action scans the posts directory and updates the corresponding pages in the Notion database.
  2. Notion → Repository Another GitHub Action periodically checks the Notion database for new or updated pages and synchronises them back into the repository as Markdown files.

This allows content to be written either locally or inside Notion while keeping the repository and database aligned.

Repository → Notion

Whenever a push occurs in the repository:

  1. GitHub Actions scans the local posts directory.
  2. Markdown files are parsed to extract metadata such as title, date, description and category.
  3. The workflow checks whether a corresponding page already exists in the Blog posts database.
  4. If the page exists, the content and metadata are updated.
  5. If not, a new page is created in the database. This keeps the Notion database aligned with the current state of the repository.

Notion → Repository

A second workflow runs periodically to pull content back from Notion.

During each run:

  1. The workflow queries the Blog posts database through the Notion API.
  2. It detects new or updated pages since the last sync.
  3. Page content is converted into Markdown.
  4. Files are written to the repository’s posts directory. If a post already exists locally it is updated, otherwise a new Markdown file is created.

Image handling

Images are normalised during synchronisation.

Regardless of where the image originates from:

  • images uploaded to Notion
  • images stored locally
  • externally hosted images All images are downloaded and stored in the website’s assets directory.

This ensures that the final website only references images hosted inside the project.

Path normalisation

When syncing posts to Notion, relative paths must be converted to absolute URLs so that they render correctly outside the repository.

For example:

../../assets/example.png

is converted to

https://your-domain/assets/example.png

This works because Astro generates a predictable asset structure.

Benefits

This setup provides several advantages:

  • Posts can be edited either locally or in the Notion Blog posts database.
  • The repository remains the authoritative source for the final website content.
  • Images are consolidated into a single assets directory.
  • Scheduled synchronisation ensures that changes in Notion are regularly pulled back into the repository. Together these workflows create a lightweight content management system that combines the convenience of Notion with the reliability of version-controlled content.