TPsoft.org/MD2HTML
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

pridaná generovaná navigácia z H1–H3 s unikátnymi ID,

Browse Source 
pridaný responzívny panel a ukladanie stavu podľa URL,
pridané verzovanie CSS a JS pomocou MD5 hashov,
aktualizovaná dokumentácia
This commit is contained in:
IgorMino
2026-10-26 19:08:34 +01:00
parent 7b39f26c99
commit 715a0e354b
5 changed files with 325 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+35 -13
View File
@@ -3,25 +3,35 @@
## Purpose
This project is a small Markdown-to-HTML utility used behind NGINX.
When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts it with Parsedown, and renders HTML styled by `src/markdown.css`.
`src/toc.js` builds an interactive table of contents from the rendered headings.
## Key Files
- `src/md2html.php`: entrypoint for conversion and HTML output.
- `src/markdown.css`: visual styling for rendered Markdown (`.markdown-body`).
- `src/toc.js`: vanilla JavaScript for the table of contents and per-document panel state.
- `composer.json`: PHP dependency config (`erusev/parsedown`).
- `tests/fixtures/toc.md`: Markdown regression fixture.
- `tests/render.php`: checks PHP output and exports heading data for JS tests.
- `tests/toc.test.cjs`: Node.js tests using DOM doubles, without a browser.
- `tests/run.ps1`: PowerShell runner for PHP and JS integration checks.
## Environment Assumptions
- Project root: `D:\www\md2html`
- Markdown files are resolved from `D:\www\...`
- CSS is currently linked as `//localhost/md2html/src/markdown.css`
- CSS and JS are linked under `//localhost/md2html/src/` with `?h=<MD5 of file contents>`.
- NGINX forwards Markdown requests to `$document_root/md2html/src/md2html.php`; see README.md.
## Change Priorities
1. Keep output readable on desktop and mobile.
2. Preserve Markdown semantics generated by Parsedown.
3. Avoid introducing JS unless explicitly required.
3. Keep JavaScript in `src/toc.js`, use vanilla JavaScript, and avoid unnecessary dependencies.
4. Keep the utility simple and fast.
## Styling Rules (`src/markdown.css`)
- Style only inside `.markdown-body` unless there is a strong reason to change global page behavior.
- Navigation is outside `.markdown-body`; scope its styles to `.md2html-toc*` and `.md2html-document` where possible.
- At widths above 760px, the open panel must leave space for the document; at smaller widths, use a dismissible overlay.
- Keep the toggle fixed and available, the panel independently scrollable, and reduced-motion preferences respected.
- Must cover: headings, links, lists, blockquotes, inline code, code blocks, tables, images, hr.
- Keep strong contrast and accessible font sizes.
- Ensure long code lines and wide tables remain usable on small screens (`overflow-x`).
@@ -29,20 +39,32 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i
## PHP Rules (`src/md2html.php`)
- Keep dependency loading via the project root's `vendor/autoload.php`, resolved relative to the entrypoint directory.
- Keep response minimal: `<!doctype html>`, UTF-8 meta, stylesheet link, wrapped content.
- Keep response minimal: `<!doctype html>`, UTF-8 and viewport meta, stylesheet link, deferred script, navigation controls, and wrapped content.
- Keep CSS and JS URLs versioned using `md5_file()` on paths relative to `__DIR__`.
- 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.
- Do not remove `.md` extension guard.
- Any path-handling changes must remain compatible with Windows paths.
## Recommended Validation After Edits
1. Open at least one Markdown file with:
- headings (`#`, `##`, `###`)
- lists
- fenced code block
- table
- blockquote
- image
2. Verify layout on desktop and mobile width.
3. Verify links and code blocks remain readable.
## Table of Contents Rules (`src/toc.js`)
- Build navigation from rendered H1–H3 in `.markdown-body`, preserving order and indicating levels with indentation. Do not add a Markdown parser.
- Keep existing unique IDs, generate collision-free IDs for other headings, and retain native anchor navigation.
- Use DOM creation and `textContent` for heading labels; do not insert untrusted content through `innerHTML`.
- Default to closed. Store panel state under `md2html:toc:` + pathname + query string, excluding the fragment.
- Handle unavailable localStorage without disabling navigation.
- Maintain ARIA state, keyboard access, Escape dismissal, mobile close controls, and readable output without JavaScript.
## Validation After Edits
- Never use a browser or browser automation. Leave visual browser verification to Igor; use non-browser checks instead.
- Run relevant checks from the project root:
- `php -l src/md2html.php`
- `php -l tests/render.php` when changing the PHP test helper.
- `node --check src/toc.js`
- `./tests/run.ps1`
- `git diff --check`
- 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.
- 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
- Building a full CMS.