Руководство 4: опубликовать заметку

$ опубликовано 2026-11-11 | | обновлено 2026-11-14
Контекст: Создание Fragments, стабильные ID, изображения, превью главной, пагинация, переводы, Giscus и публикация.

Короткие мысли, изображения и код с постоянными ссылками и необязательными комментариями.


Вывод
слов 759 токенов 987

Это руководство 4 из 8. Порядок всех руководств · Справочник настроек.

Для короткой мысли, изображения или кода не обязательно писать полную статью. Fragments собирает такие заметки в отдельном хронологическом списке и предоставляет превью последних записей на главной.

Статья рассчитана на текущий интеграционный starter. Если в существующем проекте нет команды или функции, сначала выполните обновление по первому руководству.

1. Включите список заметок

Откройте src/site.config.ts и объедините fragments ниже с существующим theme. Не создавайте второй одноимённый объект:

theme: {
  fragments: {
    enabled: true,
    pageSize: 20,
    comments: { enabled: false },
  },
},
Поле Значение по умолчанию и действие
theme.fragments.enabled false; после включения создаёт списки включённых языков и позволяет главной показывать превью при наличии контента
theme.fragments.pageSize 20; целое 1–100, число заметок на странице независимо от размера списка статей
theme.fragments.comments.enabled false; включает окно комментариев заметок, дополнительно нужны настройки репозитория Giscus ниже

Запустите npm run dev и откройте /<locale>/fragments/ по адресу терминала, например /en/fragments/ или /zh/fragments/. Соответствующий язык должен быть включён. Без контента показывается пустой список, создавать файл страницы не нужно. При отключённых заметках список и вход главной не создаются, но Markdown не удаляется.

2. Создайте заметку стандартным способом

В корне проекта выполните:

npm run new-fragment

Без --locales или ANGLEFEINT_LOCALES создаются заготовки одной заметки для всех включённых языков; изначально их девять. Файлы находятся в src/content/fragments/<locale>/, имеют общие ID и время одного запуска, но текст не переводится. Терминал выводит реальные пути. Имя вроде 2026-11-13-q8Lm3XzP.md содержит дату UTC и случайный ID. Откройте свой созданный файл, а не создавайте вручную имя из примера.

Только для китайского можно использовать npm run new-fragment -- --locales zh, для нескольких — --locales en,zh. Выберите нужный вариант вместо стандартного, не выполняйте всё подряд; команды не включают языки автоматически. До публикации перенесите незавершённые заготовки других языков за пределы каталога заметок.

Каждый запуск создаёт новую заметку. Для продолжения существующей редактируйте её файл, не запускайте создание заново. Slug не требуется, существующие файлы не перезаписываются.

В текущем starter есть скрипт new-fragment. Если его нет в старом проекте, убедитесь в обновлении темы и используйте CLI проекта:

npx @anglefeint/astro-theme new-fragment

Это альтернативная запись предыдущей команды, а не вторая команда для «той же» заметки.

3. Замените текст-заполнитель, сохранив ID

В начале файла frontmatter, текст начинается после второго ---. Сохраните созданные id и pubDate, заменив заполнитель своей мыслью. Ниже лишь формат: не заменяйте собственный ID примером:

---
id: 'q8Lm3XzP'
pubDate: '2026-11-13T09:00:00+08:00'
---

Сегодня решил давнюю проблему; запишу этот небольшой успех.

Сейчас поддерживаются три поля frontmatter:

Поле Как заполнить
id Обязателен: ровно 8 латинских букв и цифр, регистр важен. Команда создаёт и проверяет уникальность, придумывать вручную не нужно
pubDate Обязательная разбираемая дата; рекомендуется сохранить ISO команды или указать время с часовым поясом
title Необязательная строка заголовка карточки; без неё публикация тоже работает

Для заголовка добавьте title: 'Небольшой успех' в тот же frontmatter. description статьи не требуется, поля обложки heroImage нет; изображения вставляются в текст.

Список сортируется по pubDate от новых к старым, при равенстве — по ID, не по имени файла. Время страницы в UTC может отличаться от введённого локального. Изменение текста или имени файла сохраняет идентичность комментариев и ссылок; изменение даты меняет порядок и страницу списка.

После публикации сохраняйте ID. Повтор в одном языке вызывает ошибку; не используйте ID для разных заметок. Старые UUID или длинные ID не подходят. Перед обработкой совместимости сохраните оригинал: автоматической миграции ID, ссылок и комментариев нет. Массовая смена ID — не обычная уборка файлов.

Собираются только .md из src/content/fragments/, заметки .mdx не поддерживаются. Нет фильтра черновиков или будущих дат: draft: true и будущая дата ничего не скрывают. Непубличные заметки храните вне этого каталога.

4. Добавьте изображения, код и формулы

Поддерживаются обычные Markdown-абзацы, ссылки, списки и цитаты. Пример изображения:

![Снимок этого результата](/images/fragments/progress.png)

Сначала добавьте public/images/fragments/progress.png. Либо положите photo.png рядом с заметкой и используйте ![Описание изображения](./photo.png). Синтаксис, размеры и сохранение в Git см. в руководстве по изображениям.

Для кода сохраняйте ограждения Markdown и отступы:

```js
const progress = {
  done: true,
};
```

Код показывается, а не выполняется как JavaScript. Не рассчитывайте, что кнопка копирования кода и увеличение изображений из статьи автоматически работают в заметках: текущий список не подключает эти две системы взаимодействия.

При включённой общей математике заметки поддерживают встроенные $x_1$ и отдельные формулы между строками $$. Рендеринг происходит при сборке, ошибка формулы останавливает компиляцию/сборку. theme.math.enabled отключает обработку. Синтаксис см. в руководстве по статьям.

Dev, build и doctor, включая CI, подготавливают используемые локальные изображения: корректные производные используются повторно, отсутствующие, устаревшие или повреждённые создаются заново. Сохраняйте оригиналы; добавление src/assets/blog/covers/, включая manifest.json и generated/, в Git позволяет повторно использовать результаты без зависимости от кэша хостинга. Отсутствующие или недопустимые оригиналы по-прежнему вызывают ошибку. Сохраняйте Markdown вместе с оригиналами.

Требуется 0.36.2 или новее: Dev, build и doctor (включая CI) повторно используют корректные производные изображения и создают отсутствующие, устаревшие или повреждённые. В версии 0.36.1 перед build/CI сначала подготовьте изображения через dev или prepare-covers. Явная команда prepare-covers --check и синхронизация конфигурации остаются проверками без записи.

5. Превью главной и страницы списка

При включённых заметках и контенте текущего языка под header главной появляется пиксельный аватар. Он открывает превью максимум трёх последних заметок. Отдельная настройка главной не нужна, homeLatestCount статей на это не влияет.

Превью может содержать текст, первое доступное изображение и первый блок кода, но не весь текст. Высота изображений и кода ограничена с обрезкой; все изображения и блоки не показываются. Вся карточка ведёт к заметке, нижнее «число превью / общее число текущего языка →» — к полному списку. Например, для двух заметок это 2 / 2, не фиксированные три. Пустой список не показывает вход главной.

Полный список использует theme.fragments.pageSize. Первая страница — /zh/fragments/, вторая — /zh/fragments/2/. Вид и переходы пагинации используют theme.pagination, но blogPageSize не определяет количество заметок.

Переключение языка списка ведёт на первую страницу целевого языка, без гарантии того же перевода или номера страницы. Число переводов может различаться; итог каждого языка считается отдельно.

6. Поделитесь отдельной заметкой

Заметки показываются в списке без отдельных страниц деталей. Используйте ссылку даты карточки или соседнюю кнопку копирования, например:

https://your-domain.example/zh/fragments/#q8Lm3XzP

Замените домен и ID настоящими. Дата и копирование используют корень списка плюс ID независимо от текущей страницы записи. После новых заметок, изменения даты или pageSize повторная сборка и размещение обновят индекс позиционирования.

Если записи нет на странице, JavaScript по необходимости читает статический индекс языка, переходит на нужную страницу и находит её. Без JavaScript пагинация работает, но межстраничное позиционирование и копирование недоступны. При ограничениях буфера обмена показывается выделяемая ссылка для ручного копирования.

Не считайте адрес с /2/ постоянной ссылкой. Существующая старая страница может исправить устаревший якорь, но исчезнувший номер страницы даёт обычный 404: скрипт его не перехватывает. Удалённый контент, неизвестный ID или ошибка индекса сопровождаются сообщением, не восстановлением заметки.

Все ссылки заметок используют изображение для публикации списка соответствующего языка; отдельные карточки по ID не генерируются. Стандартное изображение см. в руководстве по изображениям.

7. Добавьте перевод той же заметки

Если нужны заготовки только китайского и английского, замените стандартную команду следующей:

npm run new-fragment -- --locales zh,en

Файлы одного запуска имеют общий ID и время; переводите текст самостоятельно. --locales выбирает файлы, но не включает языки. Приоритет: --locales → переменная ANGLEFEINT_LOCALES → включённые языки проекта. Отсутствие параметра не даёт автоматического перевода.

Для английского перевода уже существующей китайской заметки скопируйте её в src/content/fragments/en/, сохранив id и pubDate, затем переведите заголовок и текст. Новая команда создания выдаст другой ID и не подходит для перевода «той же» записи. Переводы могут делить ID между языками, но в одном языке двух одинаковых ID быть не должно.

Переводы с одним ID используют общие комментарии. Совпадение текста или имени файла при разных ID не связывает обсуждения.

8. Включите комментарии при необходимости

Если нужны только заметки, комментарии можно оставить выключенными. Для ответов читателей подготовьте публичный репозиторий, Discussions, приложение Giscus и категорию по руководству Giscus, получите настоящие ID и объедините с конфигурацией:

theme: {
  fragments: {
    enabled: true,
    comments: { enabled: true },
  },
  comments: {
    repo: 'yourname/your-repository',
    repoId: 'REPLACE_WITH_REPO_ID',
    category: 'Announcements',
    categoryId: 'REPLACE_WITH_CATEGORY_ID',
  },
},

Замените аккаунт, репозиторий, категорию и оба ID. Сохраните другие настройки существующего theme.comments. Отсутствие четырёх полей репозитория/категории вызывает ошибку; значения-заполнители не подтверждают правильность удалённой настройки. Вставлять Giscus script или устанавливать ещё один npm-пакет Giscus не нужно.

Переключатель заметок — theme.fragments.comments.enabled. Ради него не требуется включать комментарии статей через theme.comments.enabled; если они уже включены, сохраните свою настройку.

Комментарии заметок используют фиксированные specific, строгое совпадение и fragment/<id>. Они не используют mapping, term, number, shareAcrossLocales или фиксированный lang статей. Интерфейс следует языку страницы; переводы с одним ID делят обсуждение и реакции, но текст комментариев не переводится. Остальные общие настройки внешнего вида берутся из theme.comments.

Клиент загружается после кнопки комментариев карточки. Закрытие сохраняет экземпляр, повторное открытие или смена заметки его использует. При ошибке или неготовности примерно за 15 секунд доступен повтор: сообщение загрузки не подтверждает подключение. Для публикации посетителю нужна авторизация GitHub.

Смена ID не переносит старые комментарии, удаление заметки не удаляет обсуждение GitHub. При необходимости миграции оцените её отдельно; автоматического объединения нет.

9. Проверьте перед публикацией

В dev проверьте контент, время, превью главной и страницы. Перед публикацией остановите dev и выполните:

npm run doctor
npm run preview

doctor включает подготовку локальных изображений, проверки и сборку. После успеха сразу повторять build не нужно. В собранном preview проверьте ссылки позиционирования и изображения, а при настроенных комментариях — окно. Preview не публикует сайт; онлайн-контент меняется после повторного размещения статических файлов.

Заметки не входят в полнотекстовый поиск статей или их RSS. При сборке создаётся /zh/fragments/index.md текущего языка (для других замените zh), объединяющий публичные заметки языка с ID, временем, текстом и стабильными ссылками, а также включаемый в AI-читаемый индекс. Это публичный экспорт, не приватная резервная копия; комментариев в нём нет.

  • Нет списка: проверьте fragments и включение целевого языка.
  • Нет аватара главной: проверьте наличие заметок именно текущего языка; контента другого языка недостаточно.
  • Создание падает на старом файле: проверьте формат ID существующих Markdown; создатель читает их для проверки уникальности.
  • Повтор ID при сборке: проверьте копии в одном языке; перевод должен лежать в другом языковом каталоге.
  • Ошибка изображений: подготовьте и сохраните оригиналы, манифест и производные по руководству изображений.
  • Ошибка комментариев: проверьте настоящие ID, разрешения приложения, категорию, сеть и блокировки браузера; не меняйте ID заметки снова и снова.

Для обновления см. первое руководство.

Навигация по руководствам и настройкам

Назад: изображения · Далее: настройка страниц и функций · Все восемь руководств.

Связанные настройки: заметки, пагинация и поля, комментарии заметок. Полные пути, значения по умолчанию и ограничения — в общем справочнике.