Slidev HTML Export Verification Notes

This document describes the current HTML export behavior for NoteMD's Slidev workflow.

Current Truth

HTML export has two supported modes:

standalone - builds index-standalone.html with Slidev's standalone bundle support. This is the preferred maintainer-inspection path.
server-script - builds a normal Slidev SPA and generates local server helper scripts. This remains the compatibility path for browsers that need HTTP serving.

The current maintainer smoke test uses standalone mode by default:

npm run verify:slidev-export

Use the strict native standalone gate when the acceptance claim is specifically about index-standalone.html:

npm run verify:slidev-export -- --format html --html-mode standalone --require-native-standalone --source architecture.zh-CN.md --json

Compatibility HTML verification can still pass through server-script fallback. Strict native standalone requires htmlExport.actualMode = "standalone" and standaloneGate.passed = true.

What The Verification Covers

The maintainer command verifies more than a raw Slidev build:

NoteMD prepares a Slidev source deck from docs/architecture.zh-CN.md.
The full Slidev skill directory is discovered, including reference files.
The local Slidev fork is selected when available.
The HTML output directory is recreated before build.
The generated deck does not contain stale text from previous outputs.
The generated deck does not select an uninstalled theme.
Playwright opens the final HTML and audits the full deck by default.
Strict native standalone checks fail if the export falls back to server-script mode.
Generated inspection artifacts are not hidden by .gitignore.

Manual Verification

Run:

npm run verify:slidev-export

Expected key report fields:

{
  "ok": true,
  "htmlExport": {
    "actualMode": "standalone",
    "requiresLocalServer": false
  },
  "standaloneGate": {
    "passed": true
  },
  "slideSource": {
    "skillReferenceCount": 52
  },
  "ignoredOutputs": []
}

The exact reference count may change when the local Slidev skill changes. It should not drop to zero when the skill directory is present.

Server-Script Compatibility Path

When testing server-script mode:

npm run verify:slidev-export -- --html-mode server-script --no-playwright

Expected output files include:

index.html
assets/
start-server.sh
start-server.bat
README.md

Serve the generated directory with the generated script when manually testing browser behavior.

Security Notes

Standalone mode does not require a local HTTP server.

Server-script mode still keeps server execution explicit and user-controlled:

the plugin does not keep a persistent server running;
generated scripts serve localhost only;
the user starts and stops the server manually;
the exported files remain usable without Obsidian running.

Output Policy

The generated files under docs/export/ are local verification artifacts. Keep them available for inspection while testing, but do not commit them unless the task explicitly requires generated output.

3.1 KiB Raw Blame History