mirror of
https://github.com/jacobinwwey/obsidian-NotEMD.git
synced 2026-07-22 12:40:25 +00:00
120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
1. `standalone` - builds `index-standalone.html` with Slidev's standalone bundle support. This is the preferred maintainer-inspection path.
|
|
2. `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:
|
|
|
|
```bash
|
|
npm run verify:slidev-export
|
|
```
|
|
|
|
Use the strict native standalone gate when the acceptance claim is specifically about `index-standalone.html`:
|
|
|
|
```bash
|
|
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`.
|
|
|
|
## Fork CLI Install Path
|
|
|
|
The environment-check UI must use a real npm-installable package URL for the NoteMD Slidev fork. Do not point users at a GitHub branch, source tree, or raw file as the install target.
|
|
|
|
Current install command:
|
|
|
|
```bash
|
|
npm install -D https://github.com/Jacobinwwey/slidev/releases/download/notemd-standalone-v52.16.0-1/slidev-cli-notemd-standalone-v52.16.0-1.tgz @slidev/theme-default
|
|
```
|
|
|
|
This release asset was smoke-tested on 2026-06-21 with `npm pack --dry-run` and a clean-project `npm install`; the installed `slidev build --help` exposes `--standalone-bundle`.
|
|
|
|
Distribution rule:
|
|
|
|
1. Runtime CLI fixes, such as upstream PR `slidevjs/slidev#2633` for standalone bundle export, must be shipped through a release asset or an npm package before NoteMD links users to them.
|
|
2. Skill/reference guidance, such as upstream PR `slidevjs/slidev#2638`, is not the same distribution surface as the CLI package. It can improve deck-generation prompts when the full skill directory is available, but it should not be represented as the environment-check install target.
|
|
3. A branch, tree, blob, or raw file URL is acceptable for maintainer review only. It is not acceptable as the sidebar copyable install command because it can drift and may not pack as `@slidev/cli`.
|
|
|
|
## What The Verification Covers
|
|
|
|
The maintainer command verifies more than a raw Slidev build:
|
|
|
|
1. NoteMD prepares a Slidev source deck from `docs/architecture.zh-CN.md`.
|
|
2. The full Slidev skill directory is discovered, including reference files.
|
|
3. The local Slidev fork is selected when available.
|
|
4. The HTML output directory is recreated before build.
|
|
5. The generated deck does not contain stale text from previous outputs.
|
|
6. The generated deck does not select an uninstalled theme.
|
|
7. Playwright opens the final HTML and audits the full deck by default.
|
|
8. Strict native standalone checks fail if the export falls back to server-script mode.
|
|
9. Generated inspection artifacts are not hidden by `.gitignore`.
|
|
|
|
## Manual Verification
|
|
|
|
Run:
|
|
|
|
```bash
|
|
npm run verify:slidev-export
|
|
```
|
|
|
|
Expected key report fields:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
npm run verify:slidev-export -- --html-mode server-script --no-playwright
|
|
```
|
|
|
|
Expected output files include:
|
|
|
|
```text
|
|
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:
|
|
|
|
1. the plugin does not keep a persistent server running;
|
|
2. generated scripts serve localhost only;
|
|
3. the user starts and stops the server manually;
|
|
4. 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.
|