AmigaGuide for VS Code and Cursor

Language support for AmigaGuide hypertext documents — the .guide files that ship with AmigaOS and MorphOS software.

The preview, rendering test/sample.guide in Topaz with the Workbench 3.x palette.

The preview side-by-side with the code.

Features

Syntax highlighting for the whole markup: line commands (@database, @node, @toc, …), text attributes (@{b}, @{fg shine}, @{code}), links and their verbs, @rem comments and \ escapes. Line commands are recognised only in column 0, the way AmigaGuide itself parses them, so prose that mentions @node is left alone.

Outline and folding. Every @node appears in the breadcrumb bar and in Ctrl+Shift+O (Cmd+Shift+O), and each @node/@endnode pair folds.

Navigation.

• Ctrl+click or F12 on a link target jumps to the node.
• Targets of the form Other.guide/NODE resolve to the other file when it is in the workspace, matched case-insensitively because Amiga file systems are.
• Shift+F12 on a node name lists every link that points at it.
• AmigaGuide: Go to Node… gives a searchable list of nodes.

Completion for line commands, @{…} attributes, colour pens, link verbs, and — the useful one — node names after link, @next, @prev, @toc, @index and @help.

Hovers documenting each command and attribute; hovering a link target shows the target node's title and the first lines of its text.

Diagnostics for the mistakes that break a guide at run time rather than at build time:

A bare target that names a file next to the guide is treated as a file, not as a missing node: @{"Image" alink Flower.iff} and @{"Part 2" link Second.guide} are how graphics and split documents are linked, and Ctrl+click opens them. The .guide extension is optional, as it is on the Amiga. Such a target is reported only when there is neither a node nor a file of that name.

Links into Amiga assigns (Help:english/sys/Workbench.guide/Main) and into guides that are not in the workspace are never reported — those paths only exist on the Amiga.

Preview (Ctrl+K V / Cmd+K V, or the button in the editor title bar) renders the document the way a viewer would: one window per node, links drawn as raised Workbench buttons like the window's own, Contents, Index, Help, Previous and Next buttons from @toc/@index/@help/@prev/@next (the header forms apply to every node, a node's own override them), and a table of contents. Choose between a Workbench 3.x palette, an AmigaOS 4 palette, or your editor's own theme.

Topaz. The preview ships Patrick H. Lauke's Amiga Topaz (CC BY 3.0) so it looks like a Workbench screen with no extra fonts installed. The default stack still names the families the common conversions register as first (TopazPlus a600a1200a4000, Amiga Topaz, Topaz New, …), then the bundled family AmigaGuide Topaz, then Courier New — a Topaz you already have is used instead of the bundled one. Text is drawn at 16px on 20px lines (Topaz is an 8×8 bitmap font; whole-pixel multiples keep it sharp) and antialiasing is switched off when the preview actually resolved a pixel font, which is what makes it look like a Workbench screen rather than a word processor. Sizes and the smoothing rule are amigaguide.preview.fontSize and amigaguide.preview.pixelPerfect.

The preview follows the cursor: move to another node in the editor and the preview scrolls to it and highlights it, so a long guide stays in step with where you are editing. Turn that off with amigaguide.preview.syncCursor.

Set amigaguide.preview.autoOpen to have the preview open by itself, to the side, whenever a .guide file becomes the active editor:

"amigaguide.preview.autoOpen": true

The editor keeps focus, so you can start typing immediately. Closing a preview means that file will not reopen one until the window is reloaded — dismissing it is taken as "not for this file, not now" rather than something to undo. Links that would run something on the Amiga (system, rx, rxs, quit) are drawn as flat dashed outlines rather than buttons and are inert — the preview never executes anything. Links to nodes that do not exist get a dotted outline, so a dead link is visible without hunting through the Problems pane.

ISO-8859-1, always. AmigaGuide files are Amiga Latin-1, not UTF-8. The extension contributes a language-scoped default of files.encoding: iso88591 plus files.autoGuessEncoding: false for the amigaguide language, so .guide files open and save as Latin-1 even when your global files.encoding is utf8 — a language-scoped value wins over a plain one — and encoding auto-detection cannot second-guess it. ä, ö, ß, © and «» survive a round trip.

To override it deliberately, put your own language block in settings, which takes precedence over the extension's default:

"[amigaguide]": { "files.encoding": "utf8" }

Snippets for document headers, nodes with navigation, links, picture links, Close/Quit buttons and attributes.

Settings

Licence

The extension is MIT. See LICENSE. The preview's bundled Topaz (fonts/AmigaTopaz.ttf) is Patrick H. Lauke's Amiga Topaz, redistributed under CC BY 3.0; details in fonts/README.md.