УвійтиРозпочати

Prismic: надсилайте готові статті як чернетки

Якщо ваш сайт працює на Prismic, статтю, доведену до ладу в GetCited.me, не треба переносити поле за полем. Підключіть репозиторій один раз, скажіть GetCited.me, у які ваші поля потрапляє стаття, — і кожну готову статтю можна буде надіслати в Prismic як чернетку: її власною мовою і, за бажання, з перекладом ще на три з локалей, які вже є у вашому репозиторії.

GetCited.me ніколи нічого не публікує в Prismic. Він створює чернетки; ви їх перевіряєте й натискаєте «опублікувати».

Відео вгорі показує весь шлях приблизно за хвилину — токен, підключення, зіставлення полів, надсилання статті та її оновлення. Кроки нижче повторюють його зі знімками екрана.

Перш ніж почати

Ви маєте бути власником проєкту. Підключати репозиторій, змінювати зіставлення полів і від'єднувати його може лише власник. Учасники робочого простору бачать підключення й можуть надсилати в нього статті, щойно його налаштовано.

У репозиторії має бути тип документа, у який вміщується стаття — повторюваний тип із полем UID (slug), полем заголовка і полем rich text для тексту. Якщо такого немає (наприклад, репозиторій щойно створений і порожній), GetCited.me може створити його одразу після підключення — див. нижче.

Створіть токен на запис у Prismic

GetCited.me пише в Prismic через Write API — токеном, який ви створюєте самі й можете відкликати будь-коли:

  1. У Prismic відкрийте свій репозиторій.
  2. Перейдіть у Settings → API & Security.
  3. Відкрийте розділ Write APIs і створіть новий токен. Назвіть його так, щоб потім упізнати, наприклад «GetCited.me».
  4. Скопіюйте токен.

Токен дає GetCited.me змогу створювати й оновлювати документи в цьому репозиторії. Використовується він лише для запису чернеток.

Екрани самого Prismic потребують вашого входу в Prismic, тож їх тут не показано; картка Prismic у GetCited.me повторює цей шлях трьома пронумерованими кроками.

API вашого репозиторію приватний? Якщо в Settings → API & Security → Content API репозиторій позначено як приватний, скопіюйте з того самого екрана ще й токен доступу Content API. Він потрібен GetCited.me, щоб прочитати ваші типи документів і локалі.

Підключіть його в GetCited.me

Відкрийте Налаштування → Інтеграції і знайдіть картку Prismic.

  1. Назва або адреса репозиторію. Назва — це перша частина адреси репозиторію: my-repo у my-repo.prismic.io. Повна адреса теж підійде.
  2. Токен Write API. Вставте створений токен.
  3. Якщо API приватний, позначте API мого репозиторію приватний і вставте токен доступу Content API.
  4. Натисніть Підключити Prismic.

GetCited.me одразу перевіряє токен на цьому репозиторії. Хибний токен або репозиторій, якого не існує, мають кожен своє повідомлення на картці.

Картка Prismic із назвою репозиторію й токеном на запис, готова до підключення
Картка Prismic із назвою репозиторію й токеном на запис, готова до підключення

Ще немає типу для статей?

Якщо жоден із ваших типів не вміщує статтю, картка скаже про це після підключення й запропонує два шляхи:

  • Створити тип Blog post. GetCited.me додає у ваш репозиторій новий тип «Blog post» рівно з тими полями, які заповнює стаття: UID, заголовок, обкладинка, текст, а на вкладці SEO — meta title і meta description. Тип лише додається: Prismic не дає перезаписати наявний, тож нічого з уже наявного в репозиторії не змінюється. Далі відкривається заповнене зіставлення — натисніть Зберегти зіставлення, і все готово.
  • Скопіювати модель (JSON). Якщо модель Prismic вашого сайту ведеться в коді через Slice Machine, передайте цей файл розробнику, щоб він додав його як customtypes/blog_post/index.json — тип, створений лише в Prismic, не є частиною вашого коду. Коли тип з'явиться в репозиторії, відкрийте Змінити зіставлення.

В обох випадках сайту ще потрібна сторінка, яка показує новий тип, — інакше опубліковані статті на ньому не з'являться. Це вже робота розробника.

Після збереження токен більше ніколи не показується. Картка показує лише його останні чотири символи, щоб ви знали, який токен діє. Щоб замінити його, створіть новий токен у Prismic і скористайтеся кнопкою Замінити токен на картці.

Зіставте статтю з вашими полями

Одразу після підключення GetCited.me читає ваші типи документів і відкриває зіставлення, вже заповнене найкращим здогадом. Перевірте кожен рядок і змініть те, що не підходить:

  • Тип документа — тип, яким створюються статті.
  • UID (slug) — поле UID цього типу.
  • Заголовок — поле key text або rich text.
  • Текст статті — поле rich text або поле rich text усередині slice, якщо текст у вас збирається зі slices.
  • Meta title, Meta description, Обкладинка — необов'язкові. Залиште «Не зіставлено», якщо таких полів у типі немає.
  • Основна локаль — головна мова репозиторію.
  • Шаблон публічної адреси — необов'язково. Де опублікований документ живе на вашому сайті, з {uid} на місці slug — наприклад https://example.com/blog/{uid}. Він має використовувати адресу сайту цього проєкту. З ним GetCited.me знає публічну адресу статті, щойно ви її опублікуєте.

Натисніть Зберегти зіставлення. Картка перейде в стан Готово. Доти вона показує Потрібне зіставлення, і надіслати нічого не можна.

Зіставлення, яке пропонує GetCited.me: тип документа, UID, заголовок, текст, meta-поля, обкладинка й основна локаль
Зіставлення, яке пропонує GetCited.me: тип документа, UID, заголовок, текст, meta-поля, обкладинка й основна локаль
Картка Prismic після збереження зіставлення: «Готово», репозиторій, кінець токена, тип документа й локалі
Картка Prismic після збереження зіставлення: «Готово», репозиторій, кінець токена, тип документа й локалі

Зіставлення можна відкрити знову будь-коли кнопкою Змінити зіставлення — наприклад, коли ви додали поле до типу в Prismic.

Надішліть статтю

Відкрийте готову статтю в Центрі дій, натисніть Завершити і опублікувати й оберіть Prismic (чернетка).

  1. Мова статті в Prismic обирається заздалегідь за мовою статті. Змініть її, якщо в репозиторії ця мова називається інакше.
  2. Також перекласти — позначте до трьох інших локалей репозиторію або жодної.
  3. Натисніть Створити чернетку в Prismic.
Вікно публікації з готовим Prismic: мова статті в Prismic і «Створити чернетку в Prismic»
Вікно публікації з готовим Prismic: мова статті в Prismic і «Створити чернетку в Prismic»

Робота виконується у фоні, а прогрес видно в Command Center. Коли все готово, у вікні публікації з'являється Чернетку створено і посилання Відкрити у Prismic для кожної записаної локалі (воно читається як Відкрити en-us у Prismic — з кодом вашої локалі).

«Чернетку створено»: Prismic із кнопкою «Оновити чернетку в Prismic» і посиланням «Відкрити у Prismic»
«Чернетку створено»: Prismic із кнопкою «Оновити чернетку в Prismic» і посиланням «Відкрити у Prismic»

Як обробляються локалі:

  • Документ в основній локалі завжди створюється першим, бо Prismic прив'язує до нього всі інші мови. Якщо стаття написана іншою мовою, документ в основній локалі буде перекладом.
  • Переклади робить машина на основі статті, і вони приходять як чернетки, як і все інше. Прочитайте їх перед публікацією.
  • Той самий текст статті не перекладається на ту саму локаль двічі — повторне надсилання незміненої статті використовує попередній переклад.
  • Відредагована стаття потребує нового перекладу, і кожна стаття отримує щонайбільше дві спроби перекладу на локаль. Спроба зараховується, навіть якщо не вдалася: зіпсований переклад усе одно оплачено, і він ніколи не зберігається. Після цього на ту локаль можна надіслати лише той текст, з якого її вже перекладено (якщо такий є); вікно публікації скаже про це, а не надішле застарілий переклад.

Як обробляються зображення:

  • Обкладинка. У медіатеку репозиторію копіюється й потрапляє в поле, зіставлене як «Обкладинка», лише обкладинка, яку ви завантажили в GetCited.me. Обкладинка з Unsplash — або з будь-якого іншого сайту — не копіюється: ліцензія Unsplash дозволяє показувати фото лише з Unsplash із підписом автора, поле зображення в Prismic може містити лише зображення з вашої медіатеки, а зображення з чужого сайту не нам перезаливати. У цих випадках зіставлене поле зображення лишається порожнім — додайте обкладинку в Prismic перед публікацією.
  • Зображення в тексті статті завантажуються у вашу медіатеку, якщо зіставлене поле тексту дозволяє зображення (окрім фото з Unsplash — з тієї самої ліцензійної причини); інакше в чернетку Prismic вони не потрапляють. Разом із ними переноситься alt-текст, а підпис іде окремим абзацом одразу після зображення, бо в rich text Prismic у зображення немає підпису.
  • Кожне зображення завантажується один раз. Повторне надсилання статті, повтор після збою чи заміна чернетки використовують уже завантажені зображення, а не додають копії в медіатеку.

Як зберігається форматування статті:

  • Заголовки, абзаци, жирний, курсив, посилання (внутрішні й зовнішні) та марковані чи нумеровані списки приходять як rich text Prismic.
  • Вкладені списки стають плоскими. У rich text Prismic немає рівнів списку, тож підпункт іде одразу після свого пункту, у тому самому порядку, але без відступу.
  • Таблиці й код приходять як попередньо відформатований текст — таблиця як рядок на рядок із клітинками через |. Rich text Prismic не вміщує таблиць; якщо сайту потрібна справжня таблиця, зберіть її в Prismic.
  • Цитата стає звичайним абзацом.

Куди потрапляють чернетки

Кожен документ, створений GetCited.me, потрапляє в Migration release вашого репозиторію — реліз, у якому Prismic тримає документи, створені через Write API. Нічого з нього не опубліковано.

Дві речі, які варто знати перед публікацією:

  • Публікуєте ви, а не GetCited.me. Відкрийте Migration release у Prismic, перегляньте документи й опублікуйте їх, як і будь-що інше.
  • Публікація Migration release публікує все, що в ньому є, а не лише статтю, на яку ви дивитеся. Якщо там чекають інші імпортовані документи, перегляньте й їх, перш ніж натиснути «опублікувати».

Повторне надсилання тієї самої статті

Якщо стаття вже є в Prismic, її кнопка називається Оновити чернетку в Prismic, і натискання спершу спитає: Замінити чернетку в Prismic? Підтвердження замінить ту чернетку поточною версією статті. Зміни, внесені в чернетку в Prismic після її створення, буде втрачено, тож скопіюйте все потрібне до підтвердження. Якщо ви тим часом видалили цю чернетку в Prismic, підтвердження створить її знову.

Якщо щось пішло не так

  • «Prismic відхилив цей токен на запис». Токен відкликали або вставили з помилкою. Створіть новий і скористайтеся кнопкою Замінити токен. Доти картка показує Токен відхилено.
  • «Репозиторій Prismic із такою назвою не знайдено». Перевірте назву в адресі репозиторію.
  • «Жоден тип документа в цьому репозиторії не може містити статтю». Скористайтеся кнопкою Створити тип Blog post на картці або додайте такий тип у Prismic самі (чи через Slice Machine зі скопійованої моделі), потім відкрийте Змінити зіставлення.
  • Чернетка показує «Помилка». Вікно публікації пояснює чому. Виправте причину — найчастіше зіставлення, після того як поле в Prismic перейменували чи видалили, — і надішліть статтю знову.

Від'єднання

Від'єднати Prismic унизу картки змушує GetCited.me забути репозиторій, його токени й зіставлення полів. Документи, вже створені в Prismic, залишаються на місці. Якщо токен на запис більше не потрібен, відкличте його й у Prismic — від'єднання тут цього за вас не зробить.

Що читати далі

Оновлено