Files
MD2HTML/README.md
T

5.7 KiB

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:

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 nastav smerovanie Markdown požiadaviek, napríklad:

root /storage/www;

location ~* \.md$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /storage/tpsoft.org/MD2HTML/src/md2html.php;

    # Voliteľné povolenie pre existujúci symlink /storage/www/polyanalyzer
    fastcgi_param MD2HTML_LINK_PREFIX /polyanalyzer/;
    fastcgi_param MD2HTML_LINK_ROOT /storage/tpsoft.org/polymarket-analyzer/reports;

    fastcgi_pass unix:/run/php/php8.4-fpm.sock;
}

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.

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.

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.

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

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:

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. 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.