Publikování Markdown a HTML souborů na Synology Hermes WWW

Tento návod popisuje, jak na Synology vytvořit a zveřejnit nový Markdown nebo HTML soubor tak, aby se zobrazoval přes Hermes Markdown renderer stejně jako na Azure VM.

Nový princip publikování je:

published_files.json = seznam / manifest publikovaných souborů
index.html           = generovaný výstup z published_files.json

index.html už tedy není hlavní evidence obsahu. Hlavní evidence je JSON soubor.

Struktura adresářů na Synology

/volume1/docker/HermesWWW/
├── www/
│   ├── index.html
│   ├── published_files.json
│   ├── ...
│   └── články / markdown / html soubory
└── www-venv/
    ├── app.py
    ├── update_manifest.py
    ├── generate_index.py
    ├── venv/
    └── renderer.log

Význam:

/volume1/docker/HermesWWW/www

obsahuje veřejný obsah webu.

/volume1/docker/HermesWWW/www/published_files.json

obsahuje seznam všech souborů a metadata pro publikování.

/volume1/docker/HermesWWW/www-venv

obsahuje Flask renderer a skripty pro správu manifestu a generování indexu.

Co dělá Hermes při publikaci nového Markdownu / HTML

Při úkolu typu „vytvoř a zveřejni nový markdown/html“ se provádí tento postup:

Vytvoří se .md nebo .html soubor do adresáře www
Spustí se update_manifest.py, který rekurzivně projde www
Nový soubor se zapíše do published_files.json
V JSON se doplní nebo upraví metadata:
title
description
category
publish
Spustí se generate_index.py
Z published_files.json se vygeneruje nový index.html
Flask renderer zobrazuje .md jako HTML stránku

1. Vytvoření Markdown souboru

Příklad nového článku:

/volume1/docker/HermesWWW/www/ai/test.md

Vytvoření adresáře a souboru:

mkdir -p /volume1/docker/HermesWWW/www/ai
nano /volume1/docker/HermesWWW/www/ai/test.md

Ukázkový obsah:

# Testovací článek

Toto je test publikování Markdown souboru na Synology.

## Sekce

- bod 1
- bod 2
- bod 3

2. Aktualizace manifestu published_files.json

Po vytvoření souboru spusť:

cd /volume1/docker/HermesWWW/www-venv
./venv/bin/python update_manifest.py --root /volume1/docker/HermesWWW/www

Skript:

rekurzivně projde /volume1/docker/HermesWWW/www
→ najde všechny soubory
→ vytvoří / aktualizuje published_files.json
→ zachová existující metadata u již známých souborů
→ doplní nové soubory

Manifest je uložen zde:

/volume1/docker/HermesWWW/www/published_files.json

3. Struktura položky v published_files.json

Typická položka v JSON vypadá takto:

{
  "filename": "test.md",
  "filepath": "ai/test.md",
  "href": "/ai/test.md",
  "kind": "MD",
  "mime_type": "text/markdown",
  "size_bytes": 1234,
  "sha256": "...",
  "created": "2026-05-12T10:00:00+02:00",
  "modified": "2026-05-12T10:00:00+02:00",
  "publish": true,
  "category": "🤖 AI / agenti / Hermes",
  "title": "Testovací článek",
  "description": "Test publikování Markdown souboru na Synology."
}

Nejdůležitější pole:

Pole	Význam
`filename`	název souboru
`filepath`	relativní cesta od `/www`
`href`	URL cesta pro web
`kind`	`MD`, `HTML` nebo jiný typ
`publish`	zda se má ukázat na hlavní stránce
`category`	sekce na hlavní stránce
`title`	název karty
`description`	krátký popis karty

4. Úprava metadat v JSON

Po spuštění update_manifest.py otevři:

nano /volume1/docker/HermesWWW/www/published_files.json

Najdi nový soubor podle filepath, například:

"filepath": "ai/test.md"

A uprav metadata:

"publish": true,
"category": "🤖 AI / agenti / Hermes",
"title": "Testovací článek",
"description": "Test publikování Markdown souboru na Synology."

Pokud nechceš soubor zobrazovat na hlavním indexu, nastav:

"publish": false

Soubor bude pořád dostupný přímou URL, ale nebude jako karta na index.html.

5. Generování index.html z JSON manifestu

Po úpravě published_files.json spusť:

cd /volume1/docker/HermesWWW/www-venv
HERMES_WWW_ROOT=/volume1/docker/HermesWWW/www ./venv/bin/python generate_index.py

Tím se znovu vygeneruje:

/volume1/docker/HermesWWW/www/index.html

Index obsahuje:

Kategorie
Dle data vytvoření
Dle data změny

Důležité:

index.html se už ručně needituje jako hlavní evidence.
Generuje se z published_files.json.

6. Otevření článku

Lokálně přes Synology:

http://IP_SYNOLOGY:8090/ai/test.md

Nebo přes veřejnou doménu / reverse proxy:

https://tvoje-domena.cz/ai/test.md

7. Jak funguje Flask renderer

Když uživatel otevře .md soubor, app.py provede:

načtení .md souboru
→ převod Markdownu do HTML
→ obalení CSS šablonou
→ přidání dark/light režimu
→ přidání Mermaid podpory
→ zobrazení v prohlížeči

Díky tomu se .md soubor nestahuje, ale zobrazí se jako normální HTML stránka.

HTML soubory se servírují přímo jako HTML.

8. Důležité cesty v konfiguraci

V souboru:

/volume1/docker/HermesWWW/www-venv/app.py

má být:

WWW_ROOT = Path("/volume1/docker/HermesWWW/www")

V generate_index.py a update_manifest.py je vhodné používat buď přímo Synology cestu, nebo proměnnou prostředí:

HERMES_WWW_ROOT=/volume1/docker/HermesWWW/www

Doporučené spouštění:

cd /volume1/docker/HermesWWW/www-venv
HERMES_WWW_ROOT=/volume1/docker/HermesWWW/www ./venv/bin/python update_manifest.py
HERMES_WWW_ROOT=/volume1/docker/HermesWWW/www ./venv/bin/python generate_index.py

9. Spouštění rendereru

Renderer běží přes Flask na portu 8090.

Ruční spuštění:

cd /volume1/docker/HermesWWW/www-venv
./venv/bin/python app.py

Doporučené spuštění přes Synology Task Scheduler:

cd /volume1/docker/HermesWWW/www-venv
/volume1/docker/HermesWWW/www-venv/venv/bin/python app.py >> /volume1/docker/HermesWWW/www-venv/renderer.log 2>&1 &

10. Reverse Proxy

Synology Reverse Proxy má směřovat na Flask renderer:

Destination protocol: HTTP
Destination hostname: 127.0.0.1
Destination port: 8090

Schéma:

uživatel
↓
https://tvoje-domena.cz
↓
Synology Reverse Proxy
↓
http://127.0.0.1:8090
↓
Flask app.py
↓
/volume1/docker/HermesWWW/www

Doporučený publikační workflow

Pro publikaci nového Markdown nebo HTML souboru:

1. vytvořit .md / .html soubor do /volume1/docker/HermesWWW/www
2. spustit update_manifest.py
3. upravit metadata v published_files.json
4. spustit generate_index.py
5. otevřít článek přes Flask renderer / reverse proxy

Konkrétní příkazy:

cd /volume1/docker/HermesWWW/www-venv
HERMES_WWW_ROOT=/volume1/docker/HermesWWW/www ./venv/bin/python update_manifest.py
nano /volume1/docker/HermesWWW/www/published_files.json
HERMES_WWW_ROOT=/volume1/docker/HermesWWW/www ./venv/bin/python generate_index.py

Nejdůležitější pravidla

published_files.json je hlavní evidence obsahu.
index.html je pouze generovaný výstup.
Nový soubor se má zapsat do JSON manifestu.
Metadata pro kartu se upravují v JSON, ne ručně v index.html.

Pokud se přenáší celý web mezi Azure VM a Synology, díky published_files.json lze lépe kontrolovat, jaké soubory jsou publikované a jaké metadata se mají použít pro hlavní stránku.