Command-line and editor integration
Run hmk --help or hmk COMMAND --help for installed-version help. Paths containing spaces must be quoted.
| Command | Behavior |
|---|---|
hmk --version |
Print the compiler version. |
hmk edit note.hmn [--root DIR] [--port 8766] [--document] |
Start the local two-pane editor. --document selects strict syntax. |
hmk check note.hmn [--json] |
Parse, resolve, validate, and render; write no document. JSON output is a diagnostic array. |
hmk build note.hmn [-o OUTPUT] [--screenshot PNG] |
Export HTML or PDF. A .pdf output selects PDF. Default output is beside the source in output/. |
hmk serve note.hmn [-o OUTPUT.html] [--port 8765] |
Build web output, watch dependencies, and serve the document and assets locally. |
hmk inspect note.hmn |
Print the syntax tree as JSON. |
hmk format note.hmn [--write | --check] |
Normalize line endings and the terminating newline conservatively. Does not redesign source layout. |
hmk components [NAME] [--json] [--count] |
Inspect registered component schemas. |
hmk pack note.hmn --root DIR -o note.hmkp |
Package the source and referenced dependencies. |
hmk unpack note.hmkp NEW_DIRECTORY |
Verify and extract a bundle. |
hmk lsp |
Start the stdio language server. |
build, check, and serve accept --root, --profile NAME, --debug, and --target web|pdf. serve always renders web output. inspect and format accept --root to validate the input path. A failed compiler command exits 1; invalid command-line arguments exit 2. format --check exits 1 if formatting would change the file. Warnings do not make a valid check fail.
hmk check --json is the automation interface for language diagnostics. File-permission and other operating-system failures may be reported as ordinary stderr text. To validate an actual PDF layout, run build with a PDF output; check --target pdf validates source contracts but does not launch Chromium.
Notes editor
The editor listens on loopback only. Use the exact local URL it prints. POST actions require a per-session token and validate the origin. The editor has explicit saving, file-revision conflict detection, browser draft recovery, download, undo, selection formatting, shorthand, and note-section movement.
Browser recovery is tied to that browser and source path. Clearing browser storage removes recovered drafts. Exported interactive checkboxes and recall controls do not write back to the original source; source editing happens in hmk edit. The editor can recover an incomplete expression to keep a preview available. Such a preview is not proof that the source passes strict compilation.
Language server
Configure an LSP-capable editor to execute hmk lsp using the same Python environment as the compiler. The transport is JSON-RPC over stdin/stdout with Content-Length framing. Advertised capabilities are full-document synchronization, component/shorthand completion, hover, document symbols, formatting, and syntax/name diagnostics.
This is a lightweight authoring server. It does not perform a complete imported-project semantic build on every keystroke. Run hmk check before exporting or publishing. Incremental synchronization, rename refactoring, and workspace indexing are outside the 1.0 contract.
The source distribution includes VS Code language grammars and snippets under editors/vscode/. They are editor resources, not a published Marketplace extension; the compiler can be used from any text editor.