Files
MD2HTML/AGENTS.md
T

70 lines
4.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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: `<!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.
- 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.