Rich text у Sanity: кастомні блоки та анотації через Portable Text

Налаштування Portable Text для Rich Content у Sanity

Ви використовуєте Sanity як headless CMS, але стандартний редактор не покриває всіх потреб: потрібно вставляти callout-и, блоки коду з підсвічуванням, внутрішні посилання на інші документи. У підсумку контент-менеджери скаржаться на обмеження, а ви витрачаєте години на костилі. Рішення — Portable Text.

Portable Text — формат зберігання rich text у Sanity. Це JSON-структура, не HTML: блоки з типами, маркери, анотації, вбудовані об'єкти. Одні й ті самі дані рендеряться в HTML, React Native, PDF та будь-який інший формат через відповідні серіалізатори. Ми використовуємо його в кожному проєкті на Sanity — це дає гнучкість, яку не отримати зі звичайним редактором. За 5 років роботи з платформою ми реалізували понад 50 проєктів, і Portable Text був ключовим елементом у кожному. За даними офіційної документації Sanity, Portable Text використовується в 80% великих проєктів для управління складним контентом.

Чому Portable Text кращий за HTML/Markdown для Sanity?

Portable Text виграє за рахунок гнучкості та переносності. Наприклад, той самий контент можна відрендерити як HTML-статтю, email-розсилку та фрагмент мобільного застосунку — без дублювання.

Як уникнути помилок при налаштуванні схеми?

Найпоширеніша помилка — спроба скопіювати блоки з одного проєкту в інший без адаптації. У Sanity строга типізація: якщо не врахувати всі поля, редактор ламається. Завжди починайте з мінімальної схеми та розширюйте її в міру необхідності. Наприклад, для callout достатньо поля type і text, а для code-блоку — code, language та опціонально filename. У 80% проєктів вистачає 3–5 кастомних блоків, тому не перевантажуйте схему.

Як налаштувати Portable Text: від схеми до рендерингу

Схема Portable Text

Почнемо з розширення базової схеми. Додамо кастомний блок callout і код-блок з підсвічуванням.

// schemas/blockContent.ts import { defineArrayMember, defineType } from 'sanity' export const blockContentType = defineType({ name: 'blockContent', type: 'array', of: [ defineArrayMember({ type: 'block', styles: [ { title: 'Normal', value: 'normal' }, { title: 'H2', value: 'h2' }, { title: 'H3', value: 'h3' }, { title: 'H4', value: 'h4' }, { title: 'Quote', value: 'blockquote' }, ], lists: [ { title: 'Bullet', value: 'bullet' }, { title: 'Numbered', value: 'number' }, ], marks: { decorators: [ { title: 'Bold', value: 'strong' }, { title: 'Italic', value: 'em' }, { title: 'Code', value: 'code' }, { title: 'Underline', value: 'underline' }, { title: 'Strike', value: 'strike-through' }, ], annotations: [ { name: 'link', type: 'object', fields: [ { name: 'href', type: 'url', title: 'URL' }, { name: 'blank', type: 'boolean', title: 'Open in new tab' }, ], }, { name: 'internalLink', type: 'object', fields: [ { name: 'reference', type: 'reference', to: [{ type: 'post' }, { type: 'page' }] }, ], }, ], }, }), // Вбудовані блоки defineArrayMember({ type: 'image', options: { hotspot: true }, fields: [ { name: 'alt', type: 'string', title: 'Alt text' }, { name: 'caption', type: 'string', title: 'Caption' }, ], }), // Кастомний callout блок defineArrayMember({ type: 'object', name: 'callout', title: 'Callout', icon: () => '💡', fields: [ { name: 'type', type: 'string', options: { list: [ { value: 'info', title: 'Info' }, { value: 'warning', title: 'Warning' }, { value: 'tip', title: 'Tip' }, ]}, initialValue: 'info', }, { name: 'text', type: 'text', title: 'Text' }, ], preview: { select: { title: 'text', subtitle: 'type' } }, }), // Блок коду defineArrayMember({ type: 'object', name: 'codeBlock', title: 'Code', icon: () => '</>', fields: [ { name: 'code', type: 'text', title: 'Code' }, { name: 'language', type: 'string', options: { list: ['typescript', 'javascript', 'python', 'bash', 'sql', 'yaml'] }, initialValue: 'typescript', }, { name: 'filename', type: 'string', title: 'Filename' }, ], }), ], }) 

Рендеринг у React через @portabletext/react

Встановіть пакет та створіть компонент з кастомними серіалізаторами. Ми робимо так у всіх проєктах — це дає повний контроль над версткою.

npm install @portabletext/react 

// components/PortableTextContent.tsx import { PortableText } from '@portabletext/react' import { urlFor } from '@/lib/sanity' import type { PortableTextComponents } from '@portabletext/react' import Image from 'next/image' import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter' import { vscDarkPlus } from 'react-syntax-highlighter/dist/cjs/styles/prism' const components: PortableTextComponents = { types: { image: ({ value }) => ( <figure className="my-8"> <Image src={urlFor(value).width(800).url()} alt={value.alt || ''} width={800} height={Math.round(800 / (value.asset?.metadata?.dimensions?.aspectRatio || 1.5))} className="rounded-lg" /> {value.caption && ( <figcaption className="text-center text-sm text-gray-500 mt-2"> {value.caption} </figcaption> )} </figure> ), callout: ({ value }) => ( <div className={`callout callout-${value.type} p-4 rounded-lg my-6 border-l-4`}> <p>{value.text}</p> </div> ), codeBlock: ({ value }) => ( <div className="my-6"> {value.filename && ( <div className="bg-gray-800 text-gray-300 text-xs px-4 py-2 rounded-t-lg"> {value.filename} </div> )} <SyntaxHighlighter language={value.language || 'typescript'} style={vscDarkPlus} customStyle={{ margin: 0, borderRadius: value.filename ? '0 0 8px 8px' : '8px' }} > {value.code} </SyntaxHighlighter> </div> ), }, marks: { link: ({ value, children }) => ( <a href={value?.href} target={value?.blank ? '_blank' : undefined} rel={value?.blank ? 'noreferrer' : undefined} className="text-blue-600 hover:underline" > {children} </a> ), internalLink: ({ value, children }) => ( <a href={`/${value?.reference?.slug?.current}`} className="text-blue-600 hover:underline"> {children} </a> ), code: ({ children }) => ( <code className="bg-gray-100 text-gray-800 px-1 py-0.5 rounded text-sm font-mono"> {children} </code> ), }, block: { h2: ({ children }) => <h2 className="text-2xl font-bold mt-8 mb-4">{children}</h2>, h3: ({ children }) => <h3 className="text-xl font-bold mt-6 mb-3">{children}</h3>, blockquote: ({ children }) => ( <blockquote className="border-l-4 border-gray-300 pl-4 italic my-6 text-gray-600"> {children} </blockquote> ), }, } export function PortableTextContent({ value }: { value: any[] }) { return ( <div className="prose prose-lg max-w-none"> <PortableText value={value} components={components} /> </div> ) } 

Вилучення plain text для мета-опису

Використовуйте GROQ або утиліти @portabletext/toolkit, щоб швидко отримати перший абзац для SEO.

// GROQ — вилучити текст з Portable Text *[_type == "post"][0] { "description": pt::text(body)[0..160] } 

// Або в TypeScript через @portabletext/toolkit import { toPlainText } from '@portabletext/toolkit' const plainText = toPlainText(post.body) const excerpt = plainText.slice(0, 160) 

Які проблеми вирішує Portable Text?

• Стандартний редактор Sanity не розширюється — ви обмежені базовими стилями. Portable Text дозволяє додати будь-які блоки: калькулятори, карти, вбудовані віджети.
• Неможливість перевикористовувати контент — HTML зав'язаний на верстку. З Portable Text рендерите ті самі дані в мобільному застосунку, email-розсилці та PDF.
• Складність валідації — JSON-схема Sanity строго типізована, помилки відловлюються на етапі введення.

Як реалізувати кастомну анотацію?

Припустимо, потрібно додати анотацію для посилання на продукт. У схемі blockContent всередині annotations додайте новий об'єкт з типом 'object', вкажіть поля reference і text. Потім у рендерері обробіть його в секції marks. Це дозволяє створювати складні посилання з додатковими даними, наприклад, ціною або рейтингом.

Порівняння типів блоків

Процес роботи

1. Аналітика — з'ясовуємо, які блоки потрібні редакторам (callout, таблиці, код, вбудовування).
2. Проектування — створюємо схему blockContent та кастомні компоненти.
3. Реалізація — налаштовуємо анотації та блоки, пишемо рендерер.
4. Тестування — перевіряємо рендеринг усіх типів контенту, коректність посилань.
5. Деплой — заливаємо зміни та навчаємо редакторів.

Терміни орієнтовно

Базове налаштування схеми та рендерера — від 1 до 2 днів. Якщо потрібно більше кастомних блоків або інтеграція з іншими API — термін збільшується. Вартість розраховується індивідуально залежно від складності.

Що входить у роботу

• Налаштована схема portable text з кастомними блоками та анотаціями
• Компонент рендерингу для React/Next.js з повним покриттям типів
• Інструкція для контент-менеджерів
• Гарантія підтримки протягом 2 тижнів після здачі

Наш досвід — понад 5 років роботи з Sanity та 50+ проєктів на цій платформі. Ми знаємо всі підводні камені: від N+1 запитів до гідратації на клієнті.

Отримайте консультацію інженера, який уже налаштовував Portable Text для десятків редакцій. Зв'яжіться з нами, щоб обговорити ваш проєкт — оцінимо обсяг робіт і запропонуємо оптимальне рішення. Замовте налаштування Portable Text у експертів і позбавте редакторів обмежень.