70 lines
4.8 KiB
Markdown
70 lines
4.8 KiB
Markdown
# 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. 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.
|
||
|
||
## 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, inline style, navigation controls, wrapped content, and inline script after the content.
|
||
- 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.
|
||
- 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, 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.
|
||
|
||
## Non-Goals
|
||
- Building a full CMS.
|
||
- Adding heavy frontend frameworks.
|
||
- Replacing Parsedown unless explicitly requested.
|