includovanie CSS a JS do vystupneho HTML aby nebolo potrebne linkovat subory

This commit is contained in:
2026-11-06 10:07:37 +01:00
parent 81e31a5468
commit a9022e1fb2
3 changed files with 57 additions and 56 deletions
+40 -50
View File
@@ -1,32 +1,34 @@
# MD2HTML
Konverzia Markdown do HTML, pouzitelne aj pre priame zobrazovanie Markdown suborov pomocou webservera.
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.
Zdrojove subory su v adresari `src/`:
## Požiadavky a inštalácia
- `src/md2html.php`: vstupny bod konverzie Markdown do HTML.
- `src/markdown.css`: styly vystupneho HTML.
- `src/toc.js`: interaktivny obsah dokumentu bez externych JS zavislosti.
- 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.
Závislosti nainštaluj príkazom `composer install` v koreni projektu.
Použi PHP 8 alebo novšie s rozšírením mbstring. Projekt môže byť mimo webového koreňa.
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; verzovanie URL pomocou hashov odpadá.
## Konfigurácia NGINX
V existujúcom bloku `server` nahraď pôvodné pravidlo pre Markdown a pridaj
dve presné pravidlá pre CSS a JavaScript. Príklad pre vihorlat.tpsoft.org:
V existujúcom bloku `server` nastav smerovanie Markdown požiadaviek, napríklad:
```nginx
root /storage/www;
location = /_md2html/markdown.css {
alias /storage/tpsoft.org/MD2HTML/src/markdown.css;
}
location = /_md2html/toc.js {
alias /storage/tpsoft.org/MD2HTML/src/toc.js;
}
location ~* \.md$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME /storage/tpsoft.org/MD2HTML/src/md2html.php;
@@ -39,53 +41,41 @@ location ~* \.md$ {
}
```
Uprav socket podľa použitej verzie PHP-FPM. Súbor `fastcgi_params` musí
odovzdávať `REQUEST_URI $request_uri` a `DOCUMENT_ROOT $document_root`.
Vo Windows použi napríklad `root D:/www;`, absolútne cesty k projektu
pod `D:/apps/md2html/src/` a `fastcgi_pass 127.0.0.1:9999;` podľa nastavenia PHP.
Uprav cesty a socket podľa servera. `fastcgi_params` musí odovzdávať `REQUEST_URI $request_uri` a `DOCUMENT_ROOT $document_root`. Vo Windows použi napríklad `root D:/www;`, absolútnu cestu k `src/md2html.php` a `fastcgi_pass 127.0.0.1:9999;` podľa nastavenia PHP.
PHP vyberá Markdown podľa cesty v URL. Query string vrátane parametra
`file` nemá vplyv na výber súboru. Bežné odkazy môžu smerovať na súbory
v rámci webového koreňa. Ak URL pod nastaveným prefixom vedie cez symlink
mimo koreňa, jeho výsledný súbor musí ležať v zadanom adresári reportov.
Ak externý symlink nepotrebuješ, vynechaj oba parametre
`MD2HTML_LINK_*`. Účet PHP musí mať právo prejsť do cieľového adresára
a čítať súbory.
Staré pravidlá `location = /_md2html/markdown.css` a `location = /_md2html/toc.js` možno odstrániť po nasadení tejto verzie. Nové statické cesty nepridávaj. Produkčnú konfiguráciu tento projekt automaticky nemení. Po ručnej úprave over konfiguráciu cez `nginx -t` a načítaj ju cez `nginx -s reload`.
Parsedown spracúva aj surové HTML. Webový koreň, povolený cieľ symlinku
a ich nadradené adresáre musia spravovať dôveryhodní používatelia.
V sprístupnených adresároch publikuj iba dôveryhodný Markdown. Vo Windows
použi lokálne cesty s písmenom jednotky a vyhni sa sieťovým UNC cestám
a bodom pripojenia zväzkov v publikovanom strome.
Ak externý symlink nepotrebuješ, vynechaj oba parametre `MD2HTML_LINK_*`. Pri použití musí výsledný súbor pod daným URL prefixom ležať v explicitne povolenom cieľovom adresári. PHP musí mať právo prejsť doň a čítať súbory.
Po úprave over konfiguráciu príkazom `nginx -t` a načítaj ju príkazom
`nginx -s reload`.
## 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. Pri povolenom symlinku možno používať aj `https://example.com/polyanalyzer/report.md`.
PHP prijíma iba regulárne `.md` súbory pod kanonickým webovým koreňom alebo explicitne povoleným cieľom symlinku. 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ň, povolené 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
Tlacidlo v lavom hornom rohu otvara obsah vytvoreny z nadpisov H1 az H3.
Na desktope panel uvolni miesto vedla dokumentu, na mobile sa zobrazi ako overlay.
Zatvorit ho mozno tlacidlom, klavesom Escape alebo na mobile kliknutim mimo panelu.
Panel ma vlastne scrollovanie a odkazy smeruju na unikatne ID nadpisov.
Existujuce jednoznacne ID zostavaju zachovane.
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 uklada do localStorage pod klucom `md2html:toc:` + pathname + query string,
bez URL fragmentu. Pri nedostupnom ulozisku ovladanie funguje dalej.
Bez JavaScriptu zostava dokument citatelny, navigacne ovladanie je skryte.
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
Ak máš lokálnu sadu `tests/`, testy vyžadujú PHP s DOM rozsirenim, nainstalovane Composer zavislosti a Node.js
s podporou `node:test` a `--test-isolation=none`. Nepouzivaju prehliadac ani dalsie balicky.
PHP fixture musí nastaviť `DOCUMENT_ROOT` a `REQUEST_URI` a očakávať URL
pod `/_md2html/`. V PowerShelli z koreňa projektu spusti:
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 overuju realny vystup Parsedownu a JS spravanie pomocou modelu DOM.
Vizualne rozlozenie, skutocne scrollovanie a ovladanie v prehliadaci treba overit
manualne na desktope aj mobile.
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. 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.