Notion как Headless CMS: контент-движок для сайта

Практическое руководство по использованию Notion в качестве headless CMS — бэкенда для контента сайта. Контент редактируется в Notion, а сайт отображает его через API.

Оглавление

1. Что такое Headless CMS — как разделяются контент и фронтенд
2. Почему Notion — возможности и ограничения связки
3. Архитектура и поток данных — что происходит от редактирования до публикации
4. Полезные сценарии — два рабочих варианта применения
5. Notion API: основы — токены, доступ, запросы и пагинация
6. Подключение Notion к Astro — кастомный загрузчик и генерация страниц
7. Структура базы данных — рекомендуемые свойства контентной базы
8. Конвертация блоков — Markdown, HTML и трансформеры
9. Работа с изображениями — временные URL и локальное сохранение
10. Тарифы и лимиты — ограничения, которые нужно учитывать
11. Автоматический ребилд — webhook, расписание и polling
12. Сравнение с альтернативами — как выбрать направление
13. Типичные проблемы — быстрый поиск причин и решений
14. Быстрый старт и ссылки — минимальная последовательность действий

Что такое Headless CMS

Традиционная CMS обычно объединяет редактор и отображение сайта в одной системе. В headless CMS эти роли разделены:

Почему Notion

Notion можно использовать как источник контента для сайта, если редактору удобно работать со страницами и базами:

• Блочный редактор — страницы состоят из блоков, а API работает с блочной моделью и Notion-flavored Markdown
• Базы данных и источники данных — помогают хранить записи и свойства, по которым можно строить запросы
• API — HTTP API позволяет создавать страницы, читать контент и работать с объектами программно
• Совместная работа — подходит для командного редактирования контента
• Привычный интерфейс — редактору не приходится осваивать отдельную CMS

Архитектура и поток данных

flowchart LR
    A["Notion\n(редактирование контента)"] -->|"Notion API"| B["Astro\n(генератор сайта)"]
    B -->|"npm run build"| C["HTML/CSS/JS\n(статические файлы)"]
    C -->|"rsync / deploy"| D["VPS / Хостинг\n(nginx)"]
    D -->|"HTTPS"| E["Посетитель сайта"]

Поток данных

1. Редактирование — вы пишете и редактируете контент в Notion, как обычно
2. Билд — Astro через API забирает контент из источника данных Notion
3. Генерация — каждая запись превращается в страницу сайта
4. Деплой — готовые файлы загружаются на сервер
5. Просмотр — посетитель получает статические файлы сайта

Полезные сценарии

Сценарий 1: публикация статических страниц из Notion

Задача: редактору нужно вести статьи в Notion, а посетителям — получать отдельные страницы сайта.

Условия: есть источник данных Notion, connection или персональный токен с доступом к нему, а Astro-проект умеет выполнять сборку.

Действия: на этапе билда запросите опубликованные записи, получите содержимое страниц и преобразуйте его в HTML. Notion-hosted изображения скачайте в каталог сайта или замените внешними URL.

Проверяемый результат: после npm run build в каталоге сборки появляется HTML-страница статьи, а локальный путь к скачанному изображению открывается вместе со страницей.

Ограничение: изменение текста в Notion само по себе не меняет уже собранные статические файлы. Нужен повторный билд.

Сценарий 2: автоматический ребилд после изменения страницы

Задача: запускать сборку после изменения контента без постоянного polling API.

Условия: connection webhook, публичный HTTPS-эндпоинт и автоматизация, которая умеет вызвать CI или команду сборки.

Действия: создайте подписку на событие, подтвердите её через verification_token, проверяйте X-Notion-Signature, затем запускайте сборку по идентификатору объекта из payload.

Проверяемый результат: после изменения тестовой страницы сервер получает POST, запись появляется в журнале обработчика, а новая сборка содержит изменённый текст.

Ограничение: некоторые события агрегируются и приходят с задержкой; после события актуальное содержимое нужно получить отдельным запросом к API.

Notion API: основы

Получение токена

Для личного доступа используйте персональный токен доступа (Personal Access Token, PAT):

1. Откройте раздел Personal access tokens в Developer portal
2. Нажмите New token
3. Укажите имя и выберите возможность Notion API
4. Создайте токен, скопируйте его и сохраните в безопасном месте: повторно показать значение нельзя

Для доступа через подключение (connection) откройте Settings → Connections, установите connection и добавьте его к конкретной странице или базе через меню ... → Add connections. В меню управления connection доступно действие Retrieve an internal API token.

Ключевые эндпоинты

Для примера ниже используется endpoint источника данных. В документации Notion разделы Data sources и Databases (deprecated) ведутся отдельно; при миграции проверяйте endpoint и заголовок Notion-Version по выбранной версии API.

Пример: запрос статей из источника данных

const response = await fetch(
  `https://api.notion.com/v1/data_sources/${DATA_SOURCE_ID}/query`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${NOTION_TOKEN}`,
      'Notion-Version': '2026-03-11',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      filter: {
        property: 'Статус',
        select: { equals: 'Опубликовано' },
      },
      sorts: [
        { property: 'Порядок', direction: 'ascending' },
      ],
    }),
  }
);

const data = await response.json();
// data.results — массив страниц со свойствами

Пагинация

API использует курсорную пагинацию. Если ответ содержит has_more: true, передайте next_cursor в следующем запросе:

let allPages = [];
let cursor = undefined;

do {
  const response = await notion.dataSources.query({
    data_source_id: DATA_SOURCE_ID,
    start_cursor: cursor,
  });
  allPages.push(...response.results);
  cursor = response.has_more ? response.next_cursor : undefined;
} while (cursor);

Подключение Notion к Astro

Notion + Astro связываются через Content Collections и кастомный загрузчик. Astro поддерживает загрузчики, которые получают данные на этапе сборки. Для удалённого контента готового встроенного загрузчика нет: его нужно написать самостоятельно или подключить библиотеку сообщества.

Кастомный загрузчик

Загрузчик — функция, которая забирает данные из Notion API и превращает их в формат, понятный Astro. Асинхронный функциональный загрузчик должен вернуть массив записей с уникальным полем id либо объект, где ключи являются уникальными идентификаторами:

// src/loaders/notion-loader.ts
import { Client } from '@notionhq/client';
import { NotionToMarkdown } from 'notion-to-md';

const notion = new Client({ auth: import.meta.env.NOTION_TOKEN });
const n2m = new NotionToMarkdown({ notionClient: notion });

export async function notionLoader(dataSourceId: string) {
  const pages = await getAllPages(dataSourceId);

  return Promise.all(
    pages.map(async (page) => {
      const mdBlocks = await n2m.pageToMarkdown(page.id);
      const content = n2m.toMarkdownString(mdBlocks).parent;

      return {
        id: page.id,
        slug: getProperty(page, 'Slug'),
        title: getProperty(page, 'Name'),
        description: getProperty(page, 'Описание'),
        category: getProperty(page, 'Категория'),
        tags: getProperty(page, 'Теги'),
        order: getProperty(page, 'Порядок'),
        publishedAt: getProperty(page, 'Дата публикации'),
        content,
      };
    })
  );
}

Подключение в Content Collections

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { notionLoader } from './loaders/notion-loader';

const knowledgeBase = defineCollection({
  loader: () => notionLoader(import.meta.env.NOTION_KB_DATA_SOURCE_ID),
  schema: z.object({
    slug: z.string(),
    title: z.string(),
    description: z.string(),
    category: z.string(),
    tags: z.array(z.string()),
    order: z.number(),
    publishedAt: z.string().optional(),
    content: z.string(),
  }),
});

export const collections = { knowledgeBase };

Генерация страниц

В этом примере content содержит Markdown. Перед передачей в set:html его нужно преобразовать в HTML; ниже для этого используется marked.

---
// src/pages/knowledge/[slug].astro
import { getCollection } from 'astro:content';
import { marked } from 'marked';
import BaseLayout from '../../layouts/BaseLayout.astro';

export async function getStaticPaths() {
  const articles = await getCollection('knowledgeBase');
  return articles.map((article) => ({
    params: { slug: article.data.slug },
    props: { article },
  }));
}

const { article } = Astro.props;
const contentHtml = await marked.parse(article.data.content);
---
<BaseLayout title={article.data.title}>
  <article class="prose dark:prose-invert max-w-prose mx-auto">
    <h1>{article.data.title}</h1>
    <p class="text-gray-500">{article.data.description}</p>
    <Fragment set:html={contentHtml} />
  </article>
</BaseLayout>

Структура базы данных для CMS

Рекомендуемая схема свойств для контентной базы:

Конвертация блоков Notion в HTML

Notion API работает с блочной моделью. Кроме того, API поддерживает Notion-flavored Markdown в отдельных операциях, например при создании страницы; блочная модель нужна для точного контроля форматирования, цветов, вложенности и типов блоков.

{
  "object": "block",
  "type": "heading_2",
  "heading_2": {
    "rich_text": [
      { "plain_text": "Заголовок раздела", "annotations": { "bold": false } }
    ]
  }
}

Для конвертации блоков в Markdown или HTML можно использовать библиотеку notion-to-md:

npm install @notionhq/client notion-to-md marked

import { NotionToMarkdown } from 'notion-to-md';

const n2m = new NotionToMarkdown({ notionClient: notion });
const mdBlocks = await n2m.pageToMarkdown(pageId);
const markdown = n2m.toMarkdownString(mdBlocks).parent;

Если результатом является Markdown, перед выводом через set:html преобразуйте его выбранным Markdown-рендерером и примените подходящую для проекта санитизацию.

Кастомные трансформеры

Стандартная конвертация не покрывает все кейсы. Для callout-блоков, таблиц или встраиваний нужны кастомные трансформеры:

n2m.setCustomTransformer('callout', async (block) => {
  const text = block.callout.rich_text
    .map((t) => t.plain_text)
    .join('');
  const icon = block.callout.icon?.emoji || '💡';
  return `<div class="callout">${icon} ${text}</div>`;
});

Работа с изображениями

Notion API различает три источника файлов:

Решение: скачивание при билде

import fs from 'fs';
import path from 'path';

async function downloadImage(url, slug, index) {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Image download failed: ${response.status}`);
  }
  const buffer = await response.arrayBuffer();
  const contentType = response.headers.get('content-type') || '';
  const ext = contentType.includes('png') ? 'png' : 'jpg';
  const filename = `${slug}-${index}.${ext}`;
  const filepath = path.join('public/images/content', filename);

  fs.mkdirSync(path.dirname(filepath), { recursive: true });
  fs.writeFileSync(filepath, Buffer.from(buffer));

  return `/images/content/${filename}`;
}

Альтернатива — хранить изображения на внешнем сервисе (Cloudinary, imgix, S3) и вставлять в Notion как внешние HTTPS-ссылки.

Тарифы и лимиты

Автоматический ребилд после изменения контента

Notion поддерживает connection webhooks: при изменении страницы или базы сервис отправляет HTTP POST на ваш публичный HTTPS-эндпоинт. Это позволяет запускать ребилд без постоянного polling.

Вариант 1: Webhook Notion

1. Откройте настройки нужного connection
2. Перейдите на вкладку Webhooks и создайте подписку
3. Укажите публичный HTTPS URL и выберите события, например page.content_updated
4. Получите verification_token в первом POST-запросе и подтвердите его в настройках подписки
5. Проверяйте заголовок X-Notion-Signature перед запуском автоматизации
6. После подтверждённого события вызывайте GitHub Actions, API хостинга или собственную очередь сборки

События изменения содержимого могут агрегироваться и приходить с небольшой задержкой. Payload содержит метаданные и идентификатор объекта; актуальное содержимое после события нужно получить отдельным запросом к API.

Вариант 2: Ручной

ssh user@server 'cd /var/www/site && npm run build'

Вариант 3: GitHub Actions по расписанию

# .github/workflows/rebuild.yml
name: Rebuild site
on:
  schedule:
    - cron: '0 */6 * * *'  # каждые 6 часов
  workflow_dispatch:         # ручной запуск

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
        env:
          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
      - name: Deploy
        run: rsync -avz ./dist/ user@server:/var/www/site/

Вариант 4: Polling через n8n / Make

Если публичный webhook-обработчик недоступен, настройте polling: раз в N минут проверяйте last_edited_time. При изменении запускайте GitHub Actions через API. Этот вариант создаёт лишние запросы и реагирует медленнее, поэтому webhook предпочтительнее там, где его можно безопасно принять.

Сравнение с альтернативами

Типичные проблемы и решения

Проверка результата

После первого запуска проверьте наблюдаемые признаки успешной связки:

1. npm run build завершается без ошибки.
2. В каталоге сборки появляется HTML для тестовой записи из Notion.
3. В HTML присутствует обновлённый заголовок или текст тестовой страницы.
4. Notion-hosted изображение открывается по локальному пути сайта после скачивания при билде.
5. После изменения тестовой страницы и повторного билда в HTML появляется новая версия текста.
6. Для webhook-сценария сервер получает POST, проверка подписи проходит, а запуск сборки появляется в журнале CI.

Этот материал описывает настройку по официальной документации и примерам; фактический запуск в конкретном проекте нужно подтвердить этими проверками.

Быстрый старт

1. Создайте персональный токен доступа в Developer portal либо настройте connection в разделе Settings → Connections
2. Если используете connection, добавьте его к нужной странице или базе
3. Установите зависимости:

npm install @notionhq/client notion-to-md marked

1. Создайте .env:

NOTION_TOKEN=ntn_xxxxxxxxxxxx
NOTION_KB_DATA_SOURCE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

1. Напишите загрузчик и подключите его в content.config.ts
2. Запустите билд: npm run build
3. Измените тестовую страницу и повторите билд
4. Проверьте, что новая версия текста появилась в сгенерированном HTML, а Notion-hosted изображения сохранены локально или заменены стабильными внешними URL
5. Для автоматического обновления создайте и подтвердите webhook-подписку либо настройте сборку по расписанию

Полезные ссылки

• Notion API — документация
• Notion API Quickstart
• Notion Webhooks
• Объекты файлов Notion
• Notion SDK для JavaScript
• notion-to-md — конвертер блоков в Markdown
• Astro Content Loader API
• Notion API Changelog

Следующий шаг

Если вы используете Astro для сайта, руководство по Astro: фреймворку для молниеносных сайтов поможет продолжить настройку фронтенда и сборки.

Связанные материалы

• Статья: Как два ИИ-агента и один человек собрали этот сайт за ночь
• Блог: Notion делает агентов правильно — и вот почему это заметно
• База знаний: Notion как рабочая база

Если вы выстраиваете контентный стек для сайта, эти материалы помогут сопоставить CMS, автоматизацию и процесс сборки. Они пригодятся тем, кто выбирает между готовым инструментом и собственной связкой.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov