From 81e31a54685409ca5203024926056a5847d107d1 Mon Sep 17 00:00:00 2001 From: Agent Date: Fri, 6 Nov 2026 09:34:50 +0100 Subject: [PATCH] Document Markdown path and raw HTML invariants --- AGENTS.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d39cf4e..00879f4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,16 +10,12 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i - `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. +- An optional local `tests/` suite covers PHP rendering and TOC behavior with DOM doubles. ## Environment Assumptions -- Project root: `D:\www\md2html` -- Markdown files are resolved from `D:\www\...` -- CSS and JS are linked under `//localhost/md2html/src/` with `?h=`. -- NGINX forwards Markdown requests to `$document_root/md2html/src/md2html.php`; see README.md. +- 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/`. +- An external symlink requires an explicitly configured URL prefix and target directory. See README.md. ## Change Priorities 1. Keep output readable on desktop and mobile. @@ -43,8 +39,10 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i - 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. +- Validate the decoded URL path, including the `.md` extension, before filesystem lookup. Query parameters must never select a file. +- Require a regular Markdown file whose canonical path lies under the canonical document root or the explicitly permitted root for the requested URL prefix. +- Keep path handling compatible with Linux and Windows, including symlink and junction resolution. +- Keep Parsedown raw HTML rendering enabled. Serve Markdown from trusted sources. ## 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. @@ -58,9 +56,8 @@ When a `.md` file is requested, `src/md2html.php` loads the Markdown, converts i - 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` + - `./tests/run.ps1` when the local suite is available - `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.