Notion-Hugo Deploy

Write in Notion, publish with Hugo. Sync a Notion database to Hugo Markdown, download media into static/, and optionally deploy via GitHub Actions to Cloudflare Pages.

What it does

• Syncs Notion database entries to Hugo Markdown (titles, dates, tags, rich text)
• Downloads media to static/ with stable filenames and caching
• Incremental sync using .notion_cache.json
• Scaffolds CI for Cloudflare Pages via GitHub Actions

Requirements

• Python 3.10+
• Hugo (extended)
• Notion integration token and database
• (Optional) Cloudflare Pages project + GitHub Actions

Quick start (Hugo site)

Follow the Hugo quick start to create a site: https://gohugo.io/getting-started/quick-start/

hugo new site mysite
cd mysite
git init .

Add this repo as a submodule inside your Hugo site (no pip/uv install):

git submodule add https://github.com/binbinsh/notion-hugo-deploy
# ensure submodules are updated in CI/CD
git submodule update --init --recursive

Add a Hugo theme (example):

git submodule add https://github.com/binbinsh/hugo-trainsh.git themes/hugo-trainsh

Configuration

Set required environment variables:

• NOTION_TOKEN
• NOTION_DATABASE_ID

Local usage (run Notion sync, then Hugo)

From your Hugo site root (with submodule present):

uv venv --python 3.10
uv pip install notion-hugo-deploy/
uv run notion-hugo-deploy/scripts/notion_sync.py
hugo server -D

GitHub Actions workflow (Cloudflare Pages)

Use the provided workflow template from this repo:

mkdir -p .github/workflows/
cp notion-hugo-deploy/templates/workflows/deploy-cloudflare.yml .github/workflows/

Set repository Secrets:

• NOTION_TOKEN
• NOTION_DATABASE_ID
• CLOUDFLARE_ACCOUNT_ID
• CLOUDFLARE_API_TOKEN

Set repository Varable:

• CLOUDFLARE_PAGES_PROJECT

The workflow restores/saves cache for .notion_cache.json and static/* to avoid re-downloading unchanged media.

HTML rendering

Generated content includes HTML for images, video, audio, and links. Enable Goldmark unsafe rendering in Hugo config:

[markup.goldmark.renderer]
  unsafe = true