Блок «Утилиты» — инструкция

Раздел /utils/ — статическая страница со списком самодостаточных HTML-утилит (просмотрщики, конвертеры, мини-инструменты). Сборка идёт одной Python-командой из текстового реестра, без backend.

Содержание

Что где лежит
Формат реестра utils.tsv
Как добавить новую утилиту
Как поменять порядок
Как переименовать или поменять описание
Как удалить утилиту
Как пересобрать страницу
Частые ошибки

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

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

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

Главное правило: index.html в /utils/ — это вывод генератора. Любые ручные правки в нём затрутся при следующем запуске rebuild.sh. Меняй utils.tsv и build-index.py, не index.html.

Как открывается утилита

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

2. Формат реестра `utils.tsv`

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

filename<TAB>caption<TAB>description

Поле	Что это	Ограничения
`filename`	Имя HTML-файла в `items/`	Только латиница, цифры, точка, дефис, подчёркивание; обязательно `.html` или `.htm`; без слэшей и `..`.
`caption`	Заголовок карточки	Не пустой. Любые символы.
`description`	Короткое описание под заголовком	В одну строку, без переноса.

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

Порядок строк в TSV = порядок карточек на странице.

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

Положить самодостаточный HTML-файл в папку items/.
Добавить строку в utils.tsv через табуляцию.
Запустить rebuild.sh.

Пример: добавить утилиту `my-tool.html`

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

# 2. На сервере перенести в items/
ssh hommforever@158.160.96.21
sudo mv /tmp/my-tool.html /var/www/hommforever.ru/utils/items/
sudo chown root:root /var/www/hommforever.ru/utils/items/my-tool.html
sudo chmod 644 /var/www/hommforever.ru/utils/items/my-tool.html

# 3. Добавить строку в реестр
echo -e 'my-tool.html\tМоя утилита\tКороткое описание в одну строку.' \
  | sudo tee -a /var/www/hommforever.ru/utils/utils.tsv

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

Важно про TAB: в команде echo -e '...\t...\t...' работает потому, что \t — экранированная табуляция. Если редактируешь utils.tsv руками в редакторе, проверь, что между полями именно табы, а не пробелы.

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

Просто переставь строки в utils.tsv и пересобери:

sudo nano /var/www/hommforever.ru/utils/utils.tsv
sudo /var/www/hommforever.ru/utils/rebuild.sh

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

Меняешь caption/description — отредактируй поле в utils.tsv и пересобери.

Меняешь filename:

sudo mv items/old.html items/new.html.
Поправить первое поле строки в utils.tsv.
Пересобрать.

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

Удалить строку из utils.tsv.
(Опционально) удалить сам HTML-файл из items/.
Пересобрать.

sudo sed -i '/^old-tool\.html\t/d' /var/www/hommforever.ru/utils/utils.tsv
sudo rm /var/www/hommforever.ru/utils/items/old-tool.html
sudo /var/www/hommforever.ru/utils/rebuild.sh

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

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

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

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

Между полями не табуляции. Проверь cat -A utils.tsv | head — табы видны как ^I.

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

В реестре строка есть, файла нет. Положи файл или удали строку.

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

В filename попали недопустимые символы или нет расширения .html/.htm.

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

Браузер закэшировал. Жёсткий перезагруз: Cmd+Shift+R / Ctrl+Shift+R.

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