Блок «Демки» — инструкция

Раздел /demos/ — это статическая страница со списком самодостаточных HTML-демок. Никакого backend и базы данных нет: всё собирается одной Python-командой из текстового реестра.

1. Что где лежит

Все файлы блока — внутри одной папки /var/www/hommforever.ru/demos/. Структура:

/var/www/hommforever.ru/demos/
├── demos.tsv          ← реестр демок (одна строка = одна демка)
├── build-index.py     ← генератор страницы /demos/index.html
├── rebuild.sh         ← короткий запуск генератора
├── view.html          ← iframe-обёртка с кнопкой «← Демки»
├── index.html         ← СГЕНЕРИРОВАННАЯ страница; вручную не править
├── help.html          ← эта инструкция
├── README.md          ← краткая справка для разработчика
└── items/             ← сами HTML-файлы демок
    ├── ascii3d.html
    ├── wall-cabinet-3d.html
    ├── raytracer.html
    └── ortho3d.html

Как открывается демка

• В списке /demos/ ссылки ведут на универсальную iframe-обёртку: /demos/view.html?demo=ИМЯ.html. У неё сверху кнопка «← Демки», возвращающая к списку.
• Прямой URL standalone-файла остаётся доступен: /demos/items/ИМЯ.html. Подходит для отладки/предпросмотра без обёртки.
• Список карточек на /demos/ весь целиком кликабельный — клик в любую точку плашки открывает демку.

2. Формат реестра demos.tsv

Простой текстовый файл. Одна строка = одна демка. Поля разделены табуляцией (не пробелами!), три поля:

filename<TAB>caption<TAB>description

Строки, начинающиеся с #, и пустые строки игнорируются — это комментарии.

Порядок строк в TSV = порядок карточек на странице. Сверху файла → первая карточка слева/сверху сетки.

3. Как добавить новую демку

Три шага. Дальше — пример полного цикла.

1. Положить самодостаточный HTML-файл в папку items/. Самодостаточный = весь CSS/JS/изображения внутри одного файла или подгружаются с CDN. Папка items/ отдаётся nginx как обычные статические файлы.
2. Добавить строку в demos.tsv. Поля разделить табуляцией (Tab), не пробелами.
3. Запустить rebuild.sh — пересобрать index.html.

Пример: добавить демку my-demo.html

# 1. Скопировать файл (с локальной машины)
scp my-demo.html hommforever@158.160.96.21:/tmp/

# 2. На сервере перенести в items/ (нужны права root, файлы блока принадлежат root)
ssh hommforever@158.160.96.21
sudo mv /tmp/my-demo.html /var/www/hommforever.ru/demos/items/
sudo chown root:root /var/www/hommforever.ru/demos/items/my-demo.html
sudo chmod 644 /var/www/hommforever.ru/demos/items/my-demo.html

# 3. Добавить строку в реестр (в конец = новая карточка последней)
echo -e 'my-demo.html\tМоя демка\tКороткое описание в одну строку.' \
  | sudo tee -a /var/www/hommforever.ru/demos/demos.tsv

# 4. Пересобрать страницу
sudo /var/www/hommforever.ru/demos/rebuild.sh

4. Как поменять порядок

Просто переставь строки в demos.tsv и пересобери. Например, нужно вывести ascii3d.html первой, а ortho3d.html — последней:

sudo nano /var/www/hommforever.ru/demos/demos.tsv
# (передвинуть строки в нужном порядке, сохранить)
sudo /var/www/hommforever.ru/demos/rebuild.sh

Никаких приоритетов, чисел, weight-полей — только сам порядок строк.

5. Как переименовать или поменять описание

Если меняется только caption или description — отредактируй соответствующее поле в demos.tsv и пересобери. Имя файла трогать не нужно.

Если меняется filename (например, переименовали old.html → new.html):

1. Переименовать сам файл в items/: sudo mv items/old.html items/new.html.
2. Поправить первое поле строки в demos.tsv.
3. Пересобрать.

Внешний URL /demos/view.html?demo=old.html после этого перестанет работать — если нужны бекссылки, оставь старый файл как тонкий редирект или поменяй имя только при отсутствии внешних ссылок.

6. Как удалить демку

1. Удалить строку из demos.tsv.
2. (Опционально) удалить сам HTML-файл из items/ — если он больше не нужен. Если оставить, он будет доступен по прямому URL /demos/items/имя.html, но в списке не появится.
3. Пересобрать.

# Пример: убрать demo old-demo.html и удалить файл
sudo sed -i '/^old-demo\.html\t/d' /var/www/hommforever.ru/demos/demos.tsv
sudo rm /var/www/hommforever.ru/demos/items/old-demo.html
sudo /var/www/hommforever.ru/demos/rebuild.sh

7. Как пересобрать страницу

Любым из этих способов — все три эквивалентны:

sudo /var/www/hommforever.ru/demos/rebuild.sh
# или
cd /var/www/hommforever.ru/demos/ && sudo python3 build-index.py
# или
sudo python3 /var/www/hommforever.ru/demos/build-index.py

Генератор печатает строку вида Generated /var/www/.../index.html from /var/www/.../demos.tsv: 4 demos — это сигнал успеха. Если что-то не так — упадёт с понятной ошибкой и кодом возврата ≠ 0.

8. Частые ошибки

«нужна строка filename<TAB>caption<TAB>description»

В строке не три поля, разделённых табом. Скорее всего, табы заменились пробелами при копипасте. Проверить можно так:

cat -A /var/www/hommforever.ru/demos/demos.tsv | head
# табы видны как ^I; должно быть ровно два ^I в каждой непустой не-комментарии

«файл не найден: items/имя.html»

В реестре есть строка, но HTML-файла в items/ нет. Положи файл или удали строку из реестра.

«filename должен быть HTML-файлом без слэшей»

В filename попали недопустимые символы (пробел, кириллица, слэш) или нет расширения .html/.htm. Переименуй файл, чтобы он подходил под маску [A-Za-z0-9._-]+\.html?.

На странице ничего не поменялось

Браузер закэшировал. Жёсткий перезагруз: Cmd+Shift+R (macOS) или Ctrl+Shift+R (Linux/Windows). Если демка открыта через view.html — обновить надо именно ту вкладку.

Демка показывает «Демка не найдена»

В URL view.html?demo=... имя файла не подходит под безопасную маску (например, в нём есть слэш или нет .html) — обёртка сразу покажет ошибку, не загружая iframe. Проверь параметр.

См. также: общая инструкция по микропорталу · исходник этой страницы: /var/www/hommforever.ru/demos/help.html.