# AGENTS.md ## 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`). - An optional local `tests/` suite covers PHP rendering and TOC behavior with DOM doubles. ## Environment Assumptions - 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. 2. Preserve Markdown semantics generated by Parsedown. 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`). - Prefer CSS variables for colors and spacing to simplify future theme changes. ## 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: ``, 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. - 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. - 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` - `node --check src/toc.js` - `./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. - 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. - Adding heavy frontend frameworks. - Replacing Parsedown unless explicitly requested.