Development

Development and releases

Guide home · 简体中文

Use Node.js 22 or later:

npm ci
npm test
npm run lint
npm run build
npm run test:electron
npm run check:release

npm ci installs development dependencies, including the Electron test runtime; the installed plugin never runs it. npm run dev watches source files. TypeScript lives in src/; esbuild bundles pdf-lib, the local MathJax SVG fallback and export CSS. Distribution requires only main.js, manifest.json, and styles.css.

Styles are maintained in src/styles/callouts.css (environments and TOC), src/styles/ui.css (plugin controls), src/styles/document.css (export layout), and snippets/academic-layout.css (figures and tables). The build flattens CSS nesting and uses the same compiled callout styles in the release and export snapshots.

examples/ contains synthetic notes and images, including proofs and remarks. Native tests launch a hidden standalone Electron window, save README screenshots to screenshots/, and write PDFs and reports into output/. They verify Chromium printing and styles, but do not replace testing inside Obsidian. Set ACADEMIC_TEST_THEME to a local theme stylesheet path for additional compatibility checks. Linux CI uses Xvfb and configures Electron's sandbox helper; see ci.yml.

For releases, update package.json, the lockfile, manifest.json, versions.json, and the changelog together. Push a tag matching the manifest version. GitHub Actions tests and builds the plugin, checks reproducibility, and creates a draft release with three installable assets. See RELEASING.md.

Maintaining the documentation

Keep README focused on project features. Maintain installation, syntax, settings and troubleshooting in this Wiki, updating the matching English and Chinese pages when behavior changes. The Wiki has its own Git repository: https://github.com/Kristal-Boltinn/academic-notes.wiki.git.

WebKit and mobile acceptance

Development dependencies include Playwright and YAML test support; they are not bundled into the installed plugin. Install the test browser with npx playwright install webkit (Linux CI uses --with-deps), then run npm run test:webkit. The isolated synthetic host exercises portrait/landscape viewports, native-style title editing, selection and IME, KP and scroll stability, and the new workspace/diagram workflows. It uses no real vault.

Use mobile-acceptance.md for real iPad acceptance. WebKit automation cannot reproduce every Obsidian WKWebView, on-screen keyboard or touch-momentum behavior.

One-command deployment (2.15.5)

Keep the checkout outside the vault. After installing dependencies, run:

npm run deploy -- --vault "path/to/test-vault"

Only the three plugin assets are copied; data.json is retained. Previous assets are backed up in the checkout under output/deploy-backups/. An open target vault with CLI enabled can reload automatically. Use --obsidian for an explicit CLI path or --no-reload to install only. A local ACADEMIC_NOTES_VAULT environment variable makes npm run deploy sufficient.