Troubleshooting

Troubleshooting and compatibility

Guide home · 简体中文

General diagnostics now include indexPerformance (notes read/reused/parsed, refreshed reading fragments, elapsed time and whether the graph was rebuilt) and content-free status entries for visible paragraphs. KP reasons distinguish optimized text, native editing/selections, unsupported content/styles, processing limits and fitting failures. These explain fallback; they do not promise that every paragraph can use KP.

If you encounter an editor/scrolling problem, Pause or resume Live Preview enhancements (this session) temporarily suspends Academic Notes reference decorations and KP/indentation enhancements in the editor. Reading and export remain available; saved preferences and note text are unchanged. Use the command again to resume. It is an isolation/recovery aid, not a guarantee that a host or iPad scrolling freeze is fixed. The existing opt-in 90-second recorder remains useful for device-specific evidence.

Record a device-specific layout or scrolling issue

If Proof lines look uneven or Live Preview stops scrolling, open the affected note and run Record layout and scrolling diagnostics (90 seconds). First leave the affected paragraph visible in Reading view for a few seconds, then switch to Live Preview, edit the Proof title/body and try scrolling. Keep the same note open. Run Stop and save layout and scrolling diagnostics, or wait for recording to stop automatically after 90 seconds.

A separate _exports/academic-layout-diagnostics-*.md is written immediately and every 15 seconds, using your configured vault export folder. If restarting the app is necessary, the last saved checkpoint remains available. Send this report from iPad and optionally desktop to compare the two devices. No Mac or remote developer tools are required. Reports are ordinary Markdown notes containing a JSON code block, created through the vault API and verified by reading back the saved content. Look in the vault root, not the plugin folder. The existing general diagnostics offer Start/Stop, View recording, and Open saved report buttons; the recording can be viewed in-app even if a file write fails. Older .json recordings may be hidden by Obsidian's unsupported-file filter.

Recording is off until you run the command. It observes visible callout geometry, computed font/layout/scroll styles, KP markers and visible right-edge gaps, selection location, passive touch/scroll events, event prevention by other handlers, DOM mutation counts and plugin layout activity. Viewport resize events and anonymous hit-test results help check keyboard/overlay problems; during recording, touch/pointer events outside the selected note are classified without recording their content. Logs are bounded and listeners stop with recording or plugin unload. It does not record note text, formula source, file names, block IDs, HTML, input values or error messages, and does not upload anything. It never changes the note, theme, KP switches or editor selection. Font/style and device/version metadata are included. Review the JSON before sharing it.

A native paragraph without KP markers uses browser line breaking. All KP switches remain off by default; check the Reading and Live Preview switches separately. Diagnostics gather evidence and do not themselves fix an iPad scrolling freeze.

The export progress window shows errors. Afterwards, open diagnostics and inspect errors and lastPdfExport. Use Save diagnostic JSON to export folder to save diagnostics, normally to _exports/academic-diagnostics-*.json. Error history lasts for the current plugin session, so save it before reloading.

pdf.interfaceAvailable only checks whether the interface exists; it does not prove export succeeded. A successful export creates .report.json; on failure, a .phb.html snapshot may already exist. For more logs, open Developer Tools (Ctrl+Shift+I on Windows) and search the Console for [Academic Notes].

Problem	What to check
Equation has no number	Referenced-only is the default. Check its ID, references, excluded paths, and \notag.
Reference label is unchanged	Custom aliases are preserved; Source mode shows original syntax; duplicate IDs do not resolve.
Callout/figure styling is wrong	Disable duplicate numbering plugins or CSS snippets and check the callout type.
Unexpected colors	Check theme-following mode; normal-text-color affects text only.
Electron interface is unavailable	Run diagnostics and update the Obsidian desktop installer.
PDF export fails	Inspect progress and diagnostics; ensure local images, math, and fonts load correctly.
Numbering is stale	Run the rebuild-index command.

The minimum app version is an API requirement, not a guarantee that every OS, theme, and plugin combination has been tested. Mobile support is checked with a mock Obsidian host, a no-Node/no-Electron bundle load test, and isolated WebKit portrait/landscape regressions; an actual iPad installation still needs acceptance testing. Native PDF access depends on Electron interfaces exposed by Obsidian desktop and should be retested after application updates.

Use the synthetic mobile acceptance note to check editing, keyboard changes and scrolling inside the actual iPad app.