Гид по сайту

Каждая запись на сайте — это папка с файлом page.mdx. Внутри обычный текст в формате Markdown, а в начале — короткая «шапка» с названием, датой и типом записи. Фото лежат в той же папке. Проще всего писать в Верстаке — редакторе прямо на сайте, по секретному адресу. Он сам собирает шапку, сжимает фото и публикует запись.

Что есть на сайте

Сайт собирается заново при каждой публикации и каждое утро в 06:00 по Москве — тогда обновляются просмотры статей.

Верстак

Слева в Верстаке разделы: Редактор, Статьи и Товары (списки того, что уже на сайте, — нажмите на запись, чтобы открыть её в редакторе), Главная, Обо мне, Проекты, Разделы (заголовки и тексты блога, инструкций, магазина) и Настройки (соцсети, куда ведёт кнопка «Купить», жёлтая плашка вверху сайта).

В редакторе:

1. Поля сверху — тип записи (статья, видео, инструкция, проект или товар), заголовок, описание, дата и адрес. Адрес придумывается сам из заголовка, но его можно поправить. Для видео появится поле для кода ролика YouTube, для товара — цена, порядок в магазине и инструкция. Галочки «Только по прямой ссылке» и «Показывать на главной» — те же visibility и showOnHome, что в шапке.
2. Фото — кнопка «+ Добавить фото» или перетаскивание прямо в текст. Верстак уменьшит их до 1600 пикселей, сохранит в WebP, назовёт 01.webp, 02.webp… и вставит в текст тегом Photo. Под каждым фото видно, где оно уже стоит: «в тексте», «в карусели» или «не вставлено».
3. Карусель — отметьте у фото галочки «в карусель» в нужном порядке и нажмите «Карусель из выбранных».
4. Панель над текстом — кнопки для всего оформления из этой шпаргалки: жирный, курсив, заголовки, списки, цитата, ссылка, кнопка-ссылка, код, таблица, спойлер, клавиша, выравнивание, разделитель. Кнопка оборачивает выделенный текст, а если ничего не выделено — вставляет заготовку.
5. Вкладки — «Текст» для письма, «Превью» показывает статью так, как она будет выглядеть на сайте (и подсвечивает ошибки), «Код» — готовый page.mdx.
6. Готово — «Опубликовать» отправляет статью прямо на сайт (нужен токен GitHub, см. ниже). Без токена — «Скачать ZIP»: папка со статьёй и фото, которую можно опубликовать вручную. «Новая статья» очищает Верстак.

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

На Windows вместо Cmd — Ctrl.

Где лежат записи

Имя папки и есть адрес. Пишите его латиницей, строчными буквами, через дефис, без пробелов: pechka-burzhujka, ramka-dlya-magnitoly. Однажды опубликованный адрес лучше не менять — старые ссылки перестанут работать. Адреса инструкций не меняйте никогда: на них ведут QR-коды на изделиях.

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

Товары

Товар — такая же запись, только тип «Товар» и папка в src/app/market. Кроме обычных полей у него есть:

• цена в рублях — без неё в карточке будет «Цена по запросу», а в фид для Яндекса товар не попадёт;
• порядок — место в магазине: чем меньше число, тем выше;
• инструкция — адрес вида /instructions/zlynka, на странице товара появится кнопка «Инструкция»;
• «В продаже» — если галочку снять (available: false), карточка открывается, но кнопка «Купить» неактивна.

Фото товара — вертикальные 3:4, все одинаковые: в карточке магазина и в карусели на странице товара они показываются целиком, другие пропорции обрежутся по центру. В карточку идёт первое фото. Из магазина товар открывается «всплывающей» страницей: фото перелетает из карточки, страница выезжает снизу, кнопка «Назад» играет это обратно. Адрес при этом обычный, /market/<адрес>, его можно отправить ссылкой.

Кнопка «Купить» предлагает написать в Telegram или ВКонтакте — куда именно, задаётся в Верстаке, в «Настройках», одинаково для всех товаров.

Фид товаров для Яндекса

По адресу atrial.org/market.xml лежит каталог товаров в формате YML. Он собирается сам при каждой сборке сайта из тех же данных, что и магазин: название, цена, описание, фото и ссылка. В него попадают только товары с ценой — без цены Яндекс товар не примет. Категория определяется по названию: «Наличник…» — «Наличники», «Часы…» — «Часы», остальное — «Изделия мастерской».

Фид подключён в Яндекс Бизнесе: «Товары и цены» → «YML-фид». Яндекс Бизнес берёт у товара только первое фото и предупреждает об остальных — это не ошибка. Товар без фото Яндекс загрузит, но выглядеть в каталоге он будет плохо.

Превью ссылок

Когда ссылку на сайт отправляют в Telegram или ВКонтакте, рядом появляется картинка-превью: слева фото, справа заголовок и описание. Сайт рисует её сам при сборке.

Нет фото — на его месте пустая рамка со значком. Чтобы она сменилась фото, положите файл с нужным именем в src/images/og (для разделов) или добавьте фото в запись. Фото вертикальное, обрежется до 3:4 по центру, лучше от 900 пикселей по ширине.

Telegram и ВКонтакте запоминают превью: если ссылку уже отправляли, новое может появиться не сразу.

Типографика

Типограф сайта сам расставляет неразрывные пробелы после коротких слов и перед тире, меняет дефис между пробелами на тире, три точки на многоточие, «3–4» на «3–4» и «20×30» на «20×30». От вас нужно немного:

• кавычки — «ёлочки», внутри них „лапки“: «Наличник „Злынка“»;
• в конце заголовков точку не ставьте — ни в шапке записи, ни в ##;
• ё пишите там, где она есть: «ещё», «всё».

QR-коды на полках

На стикерах в магазинах и на карточке в наборах стоят не длинные ссылки, а короткие: atrial.org/q/mesto, atrial.org/q/prostranstvo, atrial.org/q/retrushka, atrial.org/q/merch, atrial.org/q/card. Каждая перебрасывает на нужную страницу с UTM-метками, и в Яндекс Метрике видно, сколько людей пришло с каждой полки: Отчёты → Источники → Метки UTM, кампания — название места.

Куда ведёт каждая короткая ссылка, записано в файле scripts/qr-links.mjs. Если поменять там адрес, уже напечатанный код начнёт вести на новую страницу — перепечатывать ничего не нужно. Новое место добавляется туда же одной строкой.

Сами коды удобно делать в нашем генераторе QR-кодов: он рисует коды в стиле ВКонтакте с логотипом Atrial в центре, умеет рамку с надписью, фон и карточку с фото. SVG из генератора — один контур: LightBurn открывает его сразу, без объединения в Illustrator, надписи тоже уже в кривых. Перед печатью любой код проверьте камерой телефона.

Подбор цвета наличника

На странице /colors наличник «Злынка» в 3D: можно покрасить каждую деталь, выбрать готовое сочетание и стену — бревно, брус, вагонку, кирпич или штукатурку. Все цвета сохраняются в адресе страницы, поэтому кнопка «Ссылка» копирует ссылку на эту раскраску: у получателя откроются те же цвета. «Картинка» скачивает текущий вид.

Модель — файл public/models/nalichnik-1.glb. Она собирается из STEP-файла из Компаса скриптами проекта nalichnik: tools/convert.py разбивает чертёж на детали для покраски, tools/pack.sh облегчает и сжимает модель. Названия деталей и палитры — в src/components/nalichnik/palette.ts.

Как опубликовать

Из Верстака, одной кнопкой. Нажмите «Опубликовать» — Верстак сам проверит текст на ошибки, отправит статью и фото в репозиторий одним коммитом, и через 2–3 минуты запись появится на сайте. Если запись с таким адресом уже есть, Верстак спросит, заменить ли её. Для этого один раз нужно подключить GitHub токеном.

Если вы работаете с репозиторием и на компьютере, после публикации из Верстака сделайте там git pull, чтобы забрать новую статью.

Из Верстака, вручную. Скачайте ZIP, распакуйте папку в нужный раздел и опубликуйте одним из способов ниже.

С компьютера. Создайте папку, положите в неё page.mdx и фото, затем закоммитьте и сделайте git push. Через пару минут запись появится на сайте.

Прямо на GitHub, без программ. В репозитории нажмите Add file → Create new file и впишите путь, например src/app/blog/moya-statya/page.mdx — папка создастся сама. Фото добавляются через Add file → Upload files в ту же папку. После сохранения (Commit changes) сайт пересоберётся сам.

Проще всего начать с копии существующей записи: скопируйте её папку, переименуйте и замените текст.

Шапка записи

page.mdximport { PostLayout } from '@/components/PostLayout'
import { createPostMetadata } from '@/lib/posts'
import photo01 from './01.webp'

export const post = {
  type: 'article', // 'article' — статья, 'video' — видео, 'instruction' — инструкция
  author: 'Daniil Kolbunov',
  date: '2026-10-18', // ГГГГ-ММ-ДД, по дате записи сортируются
  title: 'Печка-буржуйка из листовой стали',
  description: 'Одно-два предложения: видно в списке записей и в превью ссылки',
  youtubeId: 'dQw4w9WgXcQ', // только для type: 'video' — код из ссылки на YouTube
  visibility: 'public', // 'unlisted' — открывается только по прямой ссылке
  showOnHome: true, // false — не показывать в блоке «Блог» на главной
}

export const metadata = createPostMetadata(post)

export default ({ children }) => <PostLayout post={post}>{children}</PostLayout>

Дальше идёт сам текст статьи.

• Заголовок и описание в текст повторять не нужно — сайт выводит их сам вместе с датой.
• visibility: 'unlisted' — записи нет ни в списках, ни в RSS, поисковикам запрещено её индексировать, но по прямой ссылке она открывается. Так удобно готовить черновик или инструкцию только для QR-кода. Эта шпаргалка как раз такая.
• Видео с YouTube в России открывается плохо. Если ролик есть ещё и в Telegram, дайте в тексте ссылку и на пост в канале.

Заголовки

Внутри статьи используйте ##, ### и, если очень нужно, ####. Один знак # не нужен: главный заголовок сайт берёт из шапки.

Markdown## Раздел статьи

### Подраздел

#### Мелкий подзаголовок

Выделение текста

В Markdown нет отдельного подчёркивания, поэтому для него, маркера и индексов используются HTML-теги — внутри MDX они работают.

Абзацы разделяются пустой строкой. Чтобы перенести строку внутри абзаца, поставьте в её конце <br />.

Экранирование. Если нужно показать сам символ, который Markdown считает разметкой (*, _, #, [, `), поставьте перед ним обратную косую черту: \*, \_, \#.

Эмодзи вставляются как обычный текст: 🔥 🪟 ⚙️.

Выравнивание

По умолчанию текст выровнен по левому краю. Чтобы выровнять кусок по центру или вправо, оберните его в <Align> — пустые строки внутри обязательны, иначе Markdown в нём не сработает:

Markdown<Align to="center">

**Текст по центру**

</Align>

<Align to="right">

Подпись справа

</Align>

Варианты: left, center, right. Внутрь можно положить что угодно — несколько абзацев, список, ссылку. В Верстаке это кнопки ⇤ ↔ ⇥.

Списки

Markdown- пункт
- ещё пункт
  - вложенный пункт (два пробела в начале)

1. Первый шаг
2. Второй шаг

- [x] сделано
- [ ] ещё нет

Выглядит так:

• пункт
• ещё пункт
  • вложенный пункт

1. Первый шаг
2. Второй шаг

• сделано
• ещё нет

Ссылки

Markdown[текст ссылки](https://t.me/atrialcraft)
[другая страница сайта](/market/zlynka)
https://atrial.org — голая ссылка тоже станет кликабельной

У ссылок на другие сайты рядом с текстом сама появляется иконка сайта — например, так, и они открываются в новой вкладке. Ссылки внутри сайта пишите без домена, просто /blog/....

Если иконка не нужна:

Markdown<OgLink href="https://t.me/atrialcraft" favicon={false}>канал</OgLink>

Кнопка-ссылка — заметная кнопка с иконкой сайта, например для призыва перейти в магазин. В Верстаке — кнопка «Кнопка» на панели: впишите адрес в href и текст кнопки. Импорт не нужен.

Markdown<OgButton href="https://smlerch.ru/" variant="secondary">Купить в «Мэрче»</OgButton>

Купить в «Мэрче»

Варианты вида: primary (тёмная), secondary (светлая), outline (с рамкой), ghost (без фона).

Цитата и разделитель

Markdown> Буржуйка работает каждую зиму в режиме 24/7 уже три года.

---

Буржуйка работает каждую зиму в режиме 24/7 уже три года.

Три дефиса --- на отдельной строке рисуют горизонтальную черту.

Цитата с автором — подпись в теге <cite> на отдельной строке. Кнопка «Цитата» в Верстаке сразу добавляет пустой <cite></cite>: впишите автора или оставьте пустым — тогда подписи не будет.

Markdown> Брянская область постепенно появляется на наличниковой карте страны.
>
> <cite>Иван Хафизов, Nalichniki.com</cite>

Брянская область постепенно появляется на наличниковой карте страны.

Иван Хафизов, Nalichniki.com

Вложенная цитата — два знака >>.

Сворачиваемый блок

Удобно для длинных списков деталей или ответов на вопросы:

Markdown<details>
  <summary>Что входит в набор</summary>

33 детали, краски, кисти, клей, крепёж и зеркало.

</details>

Пустые строки вокруг текста внутри <details> обязательны — иначе Markdown в нём не сработает.

Таблица

Markdown| Материал | Толщина | Где брать |
| --- | --- | --- |
| Фанера | 6 мм | строительный рынок |
| Сталь | 5 мм | лазерная резка на заказ |

Сноски

MarkdownПластик дубеет на морозе[^1].

[^1]: Проверено на спойлерах для Arrma Kraton.

Сноски собираются внизу статьи с обратными ссылками.

Код

Блок кода оборачивается в три обратных апострофа, после них пишется язык — так включается подсветка:

Markdown```cpp
void setup() {
  Keyboard.begin();
}
```

Имя файла над блоком — добавьте title:

Markdown```cpp title="buttons.ino"
void loop() {}
```

buttons.inovoid loop() {}

Номера строк — showLineNumbers, выделить строки — номера в фигурных скобках:

Markdown```cpp {2} showLineNumbers
void setup() {
  Keyboard.begin(); // эта строка подсвечена
}
```

Cppvoid setup() {
  Keyboard.begin(); // эта строка подсвечена
}

Изменения в коде — язык diff, строки с + подсвечиваются зелёным, с - красным:

Markdown```diff
- delay(1000);
+ delay(500);
```

Diff- delay(1000);
+ delay(500);

Код в строке, внутри которого есть обратный апостроф, оборачивается в двойные: `` код с ` внутри ``.

Частые языки: js, ts, python, cpp (Arduino), bash, json, yaml, css, html, md, diff. Для текста без подсветки — text. У каждого блока кода есть кнопка «Скопировать».

Структура папок

Для проектов с прошивкой или моделями можно показать дерево файлов:

Markdown<FileTree
  tree={{
    name: 'buttons',
    children: [
      { name: 'buttons.ino', comment: 'основной скетч' },
      { name: 'case.stl', comment: 'корпус для печати' },
    ],
  }}
/>

Текст для копирования

Блок с кнопкой «Скопировать промпт» — например, для готового текста или настроек, которые читатель вставит к себе:

Markdown<CopyPrompt text="Сюда — текст, который скопируется по кнопке" />

Сюда — текст, который скопируется по кнопке

Фото

Фото кладётся в папку записи, подключается в шапке через import и вставляется тегом Photo — в нём же задаются подпись, размер и положение. Верстак делает импорт и вставку сам, остаётся вписать alt и подпись:

Markdownimport photo01 from './01.webp'

<Photo src={photo01} alt="Сварка корпуса печи" caption="Подпись под фото" />

На телефоне любое фото растягивается на всю ширину — иначе маленькое было бы не разглядеть. Кнопки выравнивания ⇤ ↔ ⇥ в Верстаке меняют align у фото, если курсор стоит на строке с ним.

Маленькое по центру:

Markdown<Photo src={photo01} alt="…" size="small" />

Среднее справа:

Markdown<Photo src={photo01} alt="…" size="medium" align="right" />

Маленькое слева, текст обтекает:

Markdown<Photo src={photo01} alt="…" size="small" align="left" wrap />

Текст статьи встанет справа от фото…

Так фото становится частью текста, как в журнале. Абзацы обтекают его справа, пока не закончится высота фото, а следующий заголовок раздела всегда начнётся уже под ним. На телефоне фото встанет над текстом во всю ширину. Подходит для небольших деталей, схем и портретов — для главных фото статьи лучше оставить полную ширину.

Старый способ — <figure> с тегом Image внутри — тоже работает:

Markdownimport photo01 from './01.webp'

<figure>
  <Image src={photo01} alt="Сварка корпуса печи" />
  <figcaption>Подпись под фото</figcaption>
</figure>

• alt — короткое описание того, что на фото. Его читают поисковики и экранные дикторы; без него фото как будто нет.
• figcaption можно не писать, если подпись не нужна.
• Файлы удобно называть по порядку: 01.webp, 02.webp…

Фото с другого сайта можно вставить обычной разметкой Markdown — но только по полной ссылке:

Markdown![Описание фото](https://example.com/photo.jpg)

Свои фото так вставлять не надо: путь вида ./01.webp в этой разметке не сработает. Для фото из папки записи — только import и Photo, как выше.

Видео с YouTube внутри текста (не как основное видео записи):

Markdown<YouTubeEmbed id="dQw4w9WgXcQ" title="Как собрать наличник" />

Карусель из нескольких фото — листается свайпом на телефоне, стрелками и перетаскиванием на компьютере, точки под фото показывают, какое открыто. В Верстаке: отметьте фото галочками «в карусель» в нужном порядке и нажмите «Карусель из выбранных» — блок добавится сам. Вручную это выглядит так:

Markdownimport photo02 from './02.webp'
import photo03 from './03.webp'

<ImageCarousel
  images={[
    { src: photo02, alt: 'Вид спереди', caption: 'Подпись к первому фото' },
    { src: photo03, alt: 'Вид сбоку', caption: 'Подпись ко второму' },
  ]}
/>

Все фото в карусели обрезаются до одной пропорции — по умолчанию 3:2, чтобы карусель не прыгала по высоте. Другая пропорция задаётся так: imageClassName="aspect-4/3", "aspect-square" или "aspect-4/5" для вертикальных. Общую подпись на всю карусель можно задать через caption="…", а отдельное фото для тёмной темы — через darkSrc: photo01dark.

Каким делать фото

Верстак сжимает фото сам: уменьшает до 1600 пикселей и сохраняет в WebP с качеством 82 %, так что всё ниже про размер, формат и вес он уже сделал. А вот соотношение сторон и обрезку выбираете вы.

Если кладёте фото в папку вручную, помните: сайт не сжимает картинки сам — посетитель скачивает ровно тот файл, который вы загрузили. Поэтому фото стоит подготовить заранее.

Размер. Колонка с текстом шириной около 670 пикселей, на телефонах и Retina-экранах нужно вдвое больше. Хватает 1600 пикселей по длинной стороне — больше никто не увидит, а файл станет тяжелее. Снимок с телефона (4000+ пикселей) обязательно уменьшайте.

Формат файла.

• WebP с качеством 75–85 % — основной формат фото на сайте. На глаз не отличается от оригинала, а весит на 25–35 % меньше JPG. Поддерживается всеми современными браузерами.
• JPG с качеством 75–85 % — тоже подходит, если WebP сделать нечем. Старый Safari не умеет сохранять WebP, и Верстак в нём сохраняет фото в JPG.
• PNG — только для скриншотов, схем и картинок с мелким текстом. Фото в PNG весит в разы больше. Скриншот тоже можно перевести в WebP: у него есть прозрачность и режим без потерь качества.
• HEIC (формат iPhone по умолчанию) не подходит — сайт его не покажет. Верстак переведёт его в WebP, если браузер умеет его открывать (Safari умеет). Иначе конвертируйте сами или включите на iPhone Настройки → Камера → Форматы → Наиболее совместимый.

Вес. Ориентир — 150–400 КБ на фото. Если больше 500 КБ, уменьшите размер или качество.

Соотношение сторон.

• 3:2 или 4:3 горизонтально — лучший вариант для статьи: фото целиком помещается на экран и не заставляет листать.
• 4:5 вертикально — максимум для вертикальных фото, как в Instagram.
• 9:16 внутри статьи не надо — на компьютере такое фото займёт больше экрана в высоту. Если снимали вертикально на телефон, обрежьте до 4:5 или 3:4.
• В карусели все фото должны быть одного соотношения, иначе она будет прыгать по высоте.
• Фото товара — вертикальное 3:4, 1200 × 1600 пикселей: так оно целиком видно и в карточке магазина, и на странице товара.

Чем сжать.

• Squoosh — в браузере, бесплатно: перетащите фото, выберите WebP, поставьте ширину 1600 и качество 80. Сразу видно и вес, и разницу в качестве.
• Просмотр на Mac — Инструменты → Настроить размер (1600 по ширине), затем Файл → Экспортировать в JPEG с ползунком качества примерно на 80 %.

Что ломает статью

MDX — это Markdown вперемешку с кодом, поэтому несколько символов в обычном тексте имеют особый смысл:

• { и } — пишите \{ и \}, иначе сайт попытается выполнить содержимое как код.
• < — пишите < (например, «напряжение < 12 В»), иначе это будет понято как тег.
• HTML-комментарии <!-- --> не работают; оставить заметку, которая не видна на сайте, можно так: {/* заметка */}.

Внутри блоков кода всё это можно писать как есть. В Верстаке такие ошибки сразу видны на вкладке «Превью». Если после публикации запись не появилась — скорее всего, ошибка в файле: она видна во вкладке Actions на GitHub, в шаге сборки.