includovanie CSS a JS do vystupneho HTML aby nebolo potrebne linkovat subory
This commit is contained in:
@@ -14,7 +14,7 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i
|
|||||||
|
|
||||||
## Environment Assumptions
|
## Environment Assumptions
|
||||||
- NGINX supplies the original request URI and the site document root via FastCGI.
|
- NGINX supplies the original request URI and the site document root via FastCGI.
|
||||||
- The project can live outside the document root. NGINX exposes exact asset URLs under `/_md2html/`.
|
- The project can live outside the document root. PHP embeds local CSS/JS into HTML; no static asset URLs are required.
|
||||||
- An external symlink requires an explicitly configured URL prefix and target directory. See README.md.
|
- An external symlink requires an explicitly configured URL prefix and target directory. See README.md.
|
||||||
|
|
||||||
## Change Priorities
|
## Change Priorities
|
||||||
@@ -35,8 +35,8 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i
|
|||||||
|
|
||||||
## PHP Rules (`src/md2html.php`)
|
## PHP Rules (`src/md2html.php`)
|
||||||
- Keep dependency loading via the project root's `vendor/autoload.php`, resolved relative to the entrypoint directory.
|
- Keep dependency loading via the project root's `vendor/autoload.php`, resolved relative to the entrypoint directory.
|
||||||
- Keep response minimal: `<!doctype html>`, UTF-8 and viewport meta, stylesheet link, deferred script, navigation controls, and wrapped content.
|
- Keep response minimal: `<!doctype html>`, UTF-8 and viewport meta, inline style, navigation controls, wrapped content, and inline script after the content.
|
||||||
- Keep CSS and JS URLs versioned using `md5_file()` on paths relative to `__DIR__`.
|
- Load CSS and JS from paths relative to `__DIR__`; safely escape closing script tags when embedding JavaScript.
|
||||||
- Do not assign anonymous functions or closures to PHP variables; use named functions or class methods.
|
- Do not assign anonymous functions or closures to PHP variables; use named functions or class methods.
|
||||||
- Output helpers should return rendered content for callers to consume.
|
- Output helpers should return rendered content for callers to consume.
|
||||||
- Validate the decoded URL path, including the `.md` extension, before filesystem lookup. Query parameters must never select a file.
|
- Validate the decoded URL path, including the `.md` extension, before filesystem lookup. Query parameters must never select a file.
|
||||||
@@ -60,7 +60,7 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i
|
|||||||
- `./tests/run.ps1` when the local suite is available
|
- `./tests/run.ps1` when the local suite is available
|
||||||
- `git diff --check`
|
- `git diff --check`
|
||||||
- Tests require PHP with DOM, Composer dependencies, and Node.js supporting `node:test` and `--test-isolation=none`.
|
- Tests require PHP with DOM, Composer dependencies, and Node.js supporting `node:test` and `--test-isolation=none`.
|
||||||
- Keep regression coverage for heading levels, formatting, code fences, duplicate and existing anchors, Unicode, empty and long contents, URL-specific state, blocked storage, mobile dismissal, asset hashes, and the `.md` guard.
|
- Keep regression coverage for heading levels, formatting, code fences, duplicate and existing anchors, Unicode, empty and long contents, URL-specific state, blocked storage, mobile dismissal, inline assets, script escaping, and the `.md` guard.
|
||||||
- DOM doubles do not verify actual layout or scrolling. Igor manually checks desktop/mobile layout, long-panel scrolling, anchor navigation, and readability of Markdown elements.
|
- DOM doubles do not verify actual layout or scrolling. Igor manually checks desktop/mobile layout, long-panel scrolling, anchor navigation, and readability of Markdown elements.
|
||||||
|
|
||||||
## Non-Goals
|
## Non-Goals
|
||||||
|
|||||||
@@ -1,32 +1,34 @@
|
|||||||
# MD2HTML
|
# 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.
|
- PHP 8.0 alebo novšie s rozšírením `mbstring`, pre NGINX aj PHP-FPM alebo FastCGI.
|
||||||
- `src/markdown.css`: styly vystupneho HTML.
|
- Composer na inštaláciu serverovej knižnice Parsedown.
|
||||||
- `src/toc.js`: interaktivny obsah dokumentu bez externych JS zavislosti.
|
- NGINX a účet PHP s právom čítať projekt aj publikované dokumenty.
|
||||||
|
|
||||||
Závislosti nainštaluj príkazom `composer install` v koreni projektu.
|
V koreňovom adresári projektu spusti:
|
||||||
Použi PHP 8 alebo novšie s rozšírením mbstring. Projekt môže byť mimo webového koreňa.
|
|
||||||
|
```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
|
## Konfigurácia NGINX
|
||||||
|
|
||||||
V existujúcom bloku `server` nahraď pôvodné pravidlo pre Markdown a pridaj
|
V existujúcom bloku `server` nastav smerovanie Markdown požiadaviek, napríklad:
|
||||||
dve presné pravidlá pre CSS a JavaScript. Príklad pre vihorlat.tpsoft.org:
|
|
||||||
|
|
||||||
```nginx
|
```nginx
|
||||||
root /storage/www;
|
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$ {
|
location ~* \.md$ {
|
||||||
include fastcgi_params;
|
include fastcgi_params;
|
||||||
fastcgi_param SCRIPT_FILENAME /storage/tpsoft.org/MD2HTML/src/md2html.php;
|
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í
|
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.
|
||||||
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
|
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`.
|
||||||
`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
|
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.
|
||||||
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
|
## Používanie a offline zobrazenie
|
||||||
`nginx -s reload`.
|
|
||||||
|
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
|
## Obsah dokumentu
|
||||||
|
|
||||||
Tlacidlo v lavom hornom rohu otvara obsah vytvoreny z nadpisov H1 az H3.
|
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.
|
||||||
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,
|
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é.
|
||||||
bez URL fragmentu. Pri nedostupnom ulozisku ovladanie funguje dalej.
|
|
||||||
Bez JavaScriptu zostava dokument citatelny, navigacne ovladanie je skryte.
|
|
||||||
|
|
||||||
## Testovanie
|
## Testovanie
|
||||||
|
|
||||||
Ak máš lokálnu sadu `tests/`, testy vyžadujú PHP s DOM rozsirenim, nainstalovane Composer zavislosti a Node.js
|
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:
|
||||||
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
|
```powershell
|
||||||
php -l src/md2html.php
|
php -l src/md2html.php
|
||||||
node --check src/toc.js
|
node --check src/toc.js
|
||||||
./tests/run.ps1
|
./tests/run.ps1
|
||||||
|
git diff --check
|
||||||
```
|
```
|
||||||
|
|
||||||
Testy overuju realny vystup Parsedownu a JS spravanie pomocou modelu DOM.
|
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.
|
||||||
Vizualne rozlozenie, skutocne scrollovanie a ovladanie v prehliadaci treba overit
|
|
||||||
manualne na desktope aj mobile.
|
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.
|
||||||
|
|||||||
+13
-2
@@ -65,6 +65,12 @@ function requestedMarkdown(): string|false
|
|||||||
return @file_get_contents($file);
|
return @file_get_contents($file);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
function inlineScript(string $source): string
|
||||||
|
{
|
||||||
|
// HTML ends a raw-text script even when the tag occurs inside a JS string/comment.
|
||||||
|
return '<script>' . preg_replace('~</(script)~i', '<\\\\/$1', $source) . '</script>';
|
||||||
|
}
|
||||||
|
|
||||||
$md = requestedMarkdown();
|
$md = requestedMarkdown();
|
||||||
if ($md === false) {
|
if ($md === false) {
|
||||||
http_response_code(404);
|
http_response_code(404);
|
||||||
@@ -75,10 +81,12 @@ require dirname(__DIR__) . '/vendor/autoload.php';
|
|||||||
$parser = new Parsedown();
|
$parser = new Parsedown();
|
||||||
|
|
||||||
echo '<!doctype html>';
|
echo '<!doctype html>';
|
||||||
|
echo '<html><head>';
|
||||||
echo '<meta charset="utf-8">';
|
echo '<meta charset="utf-8">';
|
||||||
echo '<meta name="viewport" content="width=device-width, initial-scale=1">';
|
echo '<meta name="viewport" content="width=device-width, initial-scale=1">';
|
||||||
echo '<link rel="stylesheet" href="/_md2html/markdown.css?h=' . md5_file(__DIR__ . '/markdown.css') . '">';
|
echo '<title>Markdown</title>';
|
||||||
echo '<script src="/_md2html/toc.js?h=' . md5_file(__DIR__ . '/toc.js') . '" defer></script>';
|
echo '<style>' . file_get_contents(__DIR__ . '/markdown.css') . '</style>';
|
||||||
|
echo '</head><body>';
|
||||||
echo '<button class="md2html-toc-toggle" type="button" aria-expanded="false" aria-label="Zobraziť obsah dokumentu" hidden><span aria-hidden="true">☰</span></button>';
|
echo '<button class="md2html-toc-toggle" type="button" aria-expanded="false" aria-label="Zobraziť obsah dokumentu" hidden><span aria-hidden="true">☰</span></button>';
|
||||||
echo '<div class="md2html-toc-backdrop" aria-hidden="true" hidden></div>';
|
echo '<div class="md2html-toc-backdrop" aria-hidden="true" hidden></div>';
|
||||||
echo '<nav class="md2html-toc" aria-label="Obsah dokumentu" hidden>';
|
echo '<nav class="md2html-toc" aria-label="Obsah dokumentu" hidden>';
|
||||||
@@ -90,3 +98,6 @@ echo '<div class="markdown-body">';
|
|||||||
echo $parser->text($md);
|
echo $parser->text($md);
|
||||||
echo '</div>';
|
echo '</div>';
|
||||||
echo '</div>';
|
echo '</div>';
|
||||||
|
// Inline classic scripts execute immediately; all required DOM nodes now exist.
|
||||||
|
echo inlineScript(file_get_contents(__DIR__ . '/toc.js'));
|
||||||
|
echo '</body></html>';
|
||||||
|
|||||||
Reference in New Issue
Block a user