2026-11-06 10:25:29 +01:00
2026-10-26 18:44:34 +01:00
2026-10-26 18:33:57 +01:00
2026-10-26 18:33:57 +01:00
2026-10-26 18:30:54 +01:00

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.

Konfigurácia NGINX

Spoločný snippet 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:

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:

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.

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:

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.

S
Description
Koverzia Markdown do HTML, pouzitelne aj pre priame zobrazovanie Markdown suborov pomocou webservera.
Readme AGPL-3.0
108 KiB
Languages
CSS 50.6%
JavaScript 26.8%
PHP 22.6%