Document Markdown path and raw HTML invariants
This commit is contained in:
@@ -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=<MD5 of file contents>`.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user