build-flow

Как работает `duck-garden-engine`

duck-garden-engine — это npm package, который собирает garden repo в static site.

Главная команда:

duck-garden build

В garden repo она обычно вызывается так:

npm run build

Что должно быть в garden repo

garden.config.json
package.json
src/site/notes/

Обычно также есть:

<slug>-vault/
src/site/img/user/
assets/
Attachments/

Порядок сборки

1. Чтение config

Engine читает:

garden.config.json

Если файла нет, сборка падает.

2. Подготовка workdir

Engine очищает и создаёт:

.duck-garden/work/

Туда копируется внутренний шаблон сайта.

3. Копирование опубликованных заметок

Сначала engine смотрит:

src/site/notes/

Если там есть опубликованные notes, берёт их.

Опубликованная note:

dg-publish: true

Если в src/site/notes/ опубликованных notes нет, engine ищет их по корню garden repo, пропуская служебные папки.

4. URL страниц

Если permalink задан — используется он.

Если permalink не задан, URL строится из пути:

src/site/notes/Guide/My Note.md

становится:

/guide/my-note/

5. Главная страница

Главная получает URL:

Признаки главной:

dg-home: true

или:

tags:
  - gardenEntry

Старые варианты permalink: / и dg-permalink: / тоже поддерживаются, но сотрудникам не нужно ставить их вручную.

6. Картинки

Engine копирует картинки из:

src/site/img/user/
Attachments/
assets/
<slug>-vault/

Публичные ссылки должны быть:

![Описание](/img/user/foto/example.jpg)

На выходе:

dist/img/user/foto/example.jpg

7. Runtime config

Engine пишет:

.duck-garden/work/src/site/_data/gardenConfig.json

8. Theme и SCSS

Engine получает тему, компилирует SCSS и учитывает:

garden.custom.scss

если такой файл есть в garden repo.

9. Eleventy build

Eleventy собирает:

HTML pages
graph.json
searchIndex.json
styles
optimized assets

10. Проверка index.html

Engine ожидает:

.duck-garden/work/dist/index.html

Если его нет, почти всегда проблема в Home note.

11. Копирование результата

Engine копирует:

.duck-garden/work/dist -> dist

Итог:

dist/index.html

Проверка dist

npm run assert:dist

или:

node node_modules/@duck/garden-engine/scripts/assert-dist.js

Строгие проверки:

DUCK_ASSERT_MIN_LINKS=1 npm run assert:dist
DUCK_ASSERT_BACKLINK_URL=/ npm run assert:dist

Debug images

DUCK_DEBUG_IMAGES=1 npm run build

Debug без оптимизации картинок

USE_FULL_RESOLUTION_IMAGES=true npm run build

Миграции

Команда:

npx duck-garden migrate --from 1.0.17 --to 1.0.18

Миграции лежат в:

migrations/

Формат:

1.0.17-to-1.0.18.js

Даже пустая миграция должна существовать, если upgrade workflow ожидает миграционный путь.

Дальше: проверка engine до release.

Как работает duck-garden-engine