104 lines
7.4 KiB
Markdown
104 lines
7.4 KiB
Markdown
# MD2HTML
|
|
|
|
Malý nástroj na zobrazovanie Markdown súborov cez NGINX. PHP načíta dokument podľa URL, prevedie ho pomocou Parsedown a vráti samostatné HTML s responzívnym vzhľadom a interaktívnym obsahom z nadpisov H1 až H3.
|
|
|
|
## Požiadavky a inštalácia
|
|
|
|
- PHP 8.0 alebo novšie s rozšírením `mbstring`, pre NGINX aj PHP-FPM alebo FastCGI.
|
|
- Composer na inštaláciu serverovej knižnice Parsedown.
|
|
- NGINX a účet PHP s právom čítať projekt aj publikované dokumenty.
|
|
|
|
V koreňovom adresári projektu spusti:
|
|
|
|
```sh
|
|
composer install
|
|
```
|
|
|
|
Projekt môže byť mimo webového koreňa. Nasadzuj `src/` aj `vendor/`; autoload sa načítava relatívne k PHP vstupnému bodu.
|
|
|
|
- `src/md2html.php`: výber dokumentu, konverzia a generovanie HTML.
|
|
- `src/markdown.css`: štýly, ktoré PHP vloží priamo do `<style>`.
|
|
- `src/toc.js`: vlastný JavaScript, ktorý PHP vloží do `<script>` za dokumentom.
|
|
|
|
CSS a JavaScript sú súčasťou každej HTML odpovede. Nie sú potrebné samostatné URL ani NGINX pravidlá pre statické súbory nástroja. Zdrojové CSS/JS zostávajú na serveri, ale klient ich samostatne nenačítava. Zmenený obsah sa vloží do ďalšej odpovede.
|
|
|
|
## Konfigurácia NGINX
|
|
|
|
Spoločný snippet [`nginx/md2html.conf`](nginx/md2html.conf) includuj do každého `server` bloku, kde chceš zobrazovať Markdown. Cestu k PHP súboru a PHP-FPM socket nastavíš v snippete iba raz:
|
|
|
|
```nginx
|
|
location ~* \.md$ {
|
|
include fastcgi_params;
|
|
fastcgi_param SCRIPT_FILENAME /storage/tpsoft.org/MD2HTML/src/md2html.php;
|
|
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
|
|
}
|
|
```
|
|
|
|
Konfigurácia jednotlivých webov potom obsahuje iba ich vlastný koreň a spoločný include:
|
|
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name example.com;
|
|
root /storage/www;
|
|
include /storage/tpsoft.org/MD2HTML/nginx/md2html.conf;
|
|
}
|
|
|
|
server {
|
|
listen 80;
|
|
server_name docs.example.com;
|
|
root /storage/docs;
|
|
include /storage/tpsoft.org/MD2HTML/nginx/md2html.conf;
|
|
}
|
|
```
|
|
|
|
Existujúce nastavenia domény, HTTPS a ostatných ciest ponechaj v príslušnom `server` bloku. Snippet používa jeho `root`, takže každý web číta dokumenty dostupné cez svoj koreň vrátane symlinkov. Includuj ho priamo do `server`, iba raz, pred prípadnými všeobecnejšími regulárnymi `location` pravidlami. Prefixové pravidlá s `^~` môžu spracovanie Markdownu v danom prefixe potlačiť.
|
|
|
|
Uprav cesty a socket podľa servera. `fastcgi_params` musí odovzdávať `REQUEST_URI $request_uri` a `DOCUMENT_ROOT $document_root` a nesmie pridávať inú hodnotu `SCRIPT_FILENAME`. Vo Windows použi napríklad `include D:/www/md2html/nginx/md2html.conf;`; v snippete nastav `fastcgi_param SCRIPT_FILENAME D:/www/md2html/src/md2html.php;` a `fastcgi_pass 127.0.0.1:9999;` podľa nastavenia PHP. Koreň každého webu zostáva v jeho `server` bloku.
|
|
|
|
Po úprave konfigurácie ju over cez `nginx -t` a načítaj cez `nginx -s reload`. Správanie `include` a výber `location` opisuje [oficiálna dokumentácia NGINX](https://nginx.org/en/docs/beginners_guide.html).
|
|
|
|
### Symlinky a junctiony
|
|
|
|
Ľubovoľný počet existujúcich symlinkov alebo Windows junctionov funguje cez ten istý snippet, aj keď ich ciele ležia mimo `DOCUMENT_ROOT`. Nie sú potrebné pravidlá ani povolenia pre jednotlivé prefixy. Napríklad pri `root /storage/www;`:
|
|
|
|
- `/storage/www/polyanalyzer` → `/storage/tpsoft.org/polymarket-analyzer/reports`: URL `/polyanalyzer/report.md`.
|
|
- `/storage/www/manualy` → `/storage/manualy`: URL `/manualy/navod.md`.
|
|
|
|
PHP vyhodnotí skutočný cieľ a načíta ho, ak ide o regulárny `.md` súbor a má k nemu prístup. Kontroluje sa prípona v URL aj prípona cieľového súboru. Cieľ nemusí ležať pod webovým koreňom. Prístup naďalej podlieha oprávneniam účtu PHP, prípadnému `open_basedir` a izolácii PHP-FPM.
|
|
|
|
URL sa stále mapuje cez koreň webu: absolútnu diskovú cestu ani parameter `file` nemožno použiť na výber súboru. Externé dokumenty sprístupni cez symlink alebo junction. Neplatné URL vrátane segmentov `..` zostávajú odmietnuté.
|
|
|
|
## Používanie a offline zobrazenie
|
|
|
|
Pre súbor `/storage/www/docs/navod.md` otvor napríklad `https://example.com/docs/navod.md`. URL `https://example.com/docs/navod.md?view=print#instalacia` načíta ten istý súbor; query string ani parameter `file` nevyberajú dokument. Cez existujúci symlink možno používať aj `https://example.com/polyanalyzer/report.md`.
|
|
|
|
PHP prijíma regulárne `.md` súbory dostupné cez URL cestu pod webovým koreňom vrátane symlinkov a junctionov smerujúcich mimo neho. Neplatné a nenájdené cesty vracajú 404.
|
|
|
|
HTML odpoveď možno uložiť ako `.html` a otvoriť bez internetu. Vlastný vzhľad ani ovládanie nástroja nepotrebujú sieť, externé fonty, obrázky, ikony ani JS knižnice. Používajú sa systémové fonty a textové symboly. Podporované sú nadpisy, odseky, zoznamy, tabuľky, citácie a bloky kódu; automatické syntax highlighting nie je implementované. Markdown obsah sa nevkladá do JavaScriptového kódu. Uzatváracie tagy skriptu v jeho zdroji sú escapované.
|
|
|
|
Odkazy, obrázky a surové HTML z Markdown dokumentu zostávajú zachované. Ich prípadné externé zdroje sa nebaľujú do HTML a môžu potrebovať sieť alebo pôvodné relatívne cesty. Offline záruka sa týka vlastných štýlov a ovládania nástroja. Parsedown aj naďalej povoľuje surové HTML, preto publikuj iba dôveryhodný Markdown. Webový koreň, ciele symlinkov aj nadradené adresáre musia spravovať dôveryhodní používatelia. Vo Windows používaj lokálne cesty s písmenom jednotky; vyhni sa UNC cestám a bodom pripojenia zväzkov.
|
|
|
|
Ak server pridáva Content-Security-Policy, musí povoľovať tieto inline štýly a skripty; nástroj sám CSP hlavičku nenastavuje.
|
|
|
|
## Obsah dokumentu
|
|
|
|
Tlačidlo vľavo hore otvorí obsah z nadpisov H1 až H3. Na desktope panel uvoľní miesto vedľa dokumentu, na mobile tvorí prekrytie. Má vlastné scrollovanie; zatvára sa tlačidlom, Escape alebo na mobile kliknutím mimo panelu či na odkaz. Jednoznačné existujúce ID nadpisov zostávajú zachované a ostatné sú generované bez kolízií. Odkazy používajú natívnu navigáciu na fragmenty.
|
|
|
|
Stav sa ukladá do localStorage pod kľúčom `md2html:toc:` + pathname + query string, bez fragmentu. Pri blokovanom úložisku ovládanie funguje ďalej. Bez JavaScriptu zostáva dokument čitateľný a navigačné ovládanie skryté.
|
|
|
|
## Testovanie
|
|
|
|
Sada `tests/` vyžaduje PHP s `mbstring` a DOM, Composer závislosti a Node.js s podporou `node:test` a `--test-isolation=none`. Z koreňa v PowerShelli spusti:
|
|
|
|
```powershell
|
|
php -l src/md2html.php
|
|
node --check src/toc.js
|
|
./tests/run.ps1
|
|
git diff --check
|
|
```
|
|
|
|
Testy overujú skutočný výstup Parsedown, vložené CSS/JS bez externých odkazov, absenciu sieťového načítavania vo vlastných zdrojoch, escapovanie `</script>`, diakritiku, surové HTML, URL guard a obsah dokumentu pomocou DOM modelu. Overujú aj dva externé symlinky (vo Windows junctiony) mimo testovacieho webového koreňa a odmietnutie adresárov, chýbajúcich súborov a súborov bez prípony `.md`. Spúšťajú JavaScript extrahovaný z generovanej HTML odpovede bez sieťových API. Nepoužívajú prehliadač ani ďalšie balíčky.
|
|
|
|
Skutočné rozloženie, scrollovanie, offline otvorenie uloženého HTML a desktopové/mobilné ovládanie manuálne overuje Igor. Lokálna sada neoveruje bežiaci NGINX ani produkčné HTTP hlavičky.
|