Files
MD2HTML/AGENTS.md
T

4.8 KiB
Raw Blame History

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.
  • External symlinks and junctions work without per-prefix configuration, subject to PHP filesystem access.

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 after canonical resolution; symlink and junction targets may lie outside the document root.
  • 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.