92 lines
3.7 KiB
Markdown
92 lines
3.7 KiB
Markdown
# MD2HTML
|
|
|
|
Konverzia Markdown do HTML, pouzitelne aj pre priame zobrazovanie Markdown suborov pomocou webservera.
|
|
|
|
Zdrojove subory su v adresari `src/`:
|
|
|
|
- `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.
|
|
|
|
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.
|
|
|
|
## 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:
|
|
|
|
```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;
|
|
|
|
# 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 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Po úprave over konfiguráciu príkazom `nginx -t` a načítaj ju príkazom
|
|
`nginx -s reload`.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
## 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:
|
|
|
|
```powershell
|
|
php -l src/md2html.php
|
|
node --check src/toc.js
|
|
./tests/run.ps1
|
|
```
|
|
|
|
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.
|