ScriptWeaver View source

MarkView

The built-in Markdown viewer megawidget — the same control the Player's own help window (F1 / --help) is built from. Point it at a documents root and it renders pages, resolves relative links / images / #anchors through the VFS (so it works identically loose on disk and inside a mounted .zip), keeps Back/Forward history, and hands external links to the system browser. Optional extras: a document tree sidebar, a fuzzy quick-open search palette (Ctrl-K) plus in-page find (Ctrl-F), and a multi-book library mode.

Created like any other widget — zero import — or imported for its building blocks (Renderer, Navigator, parseMarkdown).

Example

// Single documents root.
const mv = app.MarkView({ base: 'docs', sidebar: true, search: true });
mv.pack.configure({ fill: 'both', expand: true });
mv.go('index.md');

// Multi-book "library": several roots in one window, search spans them all.
const help = app.MarkView({
  books: [
    { base: sw.app.docsBase, title: 'Player Reference', apiRef: true },
    { base: '//zipfs:/app/docs', title: 'My App' },
  ],
});
help.pack.configure({ fill: 'both', expand: true });

Options

All options are construction-time.

Option Type Description
base string The documents root; links and images resolve against it through the VFS (a disk path or a //zipfs: mount). Mutually exclusive with books.
books array Multi-book library: [{ base, title, home?, apiRef? }]. Each book is a top-level node in the sidebar tree, the search index spans them all, and sidebar + search default on. apiRef: true marks the reference book that help prefers when a widget name matches in more than one book. Mutually exclusive with base.
toolbar boolean Show the Back / Forward / Home toolbar and page-title label. Default true; false gives a bare viewer driven programmatically.
sidebar boolean Show the collapsible document tree on the left. Default false (single root), true in books mode.
search boolean Enable the fuzzy quick-open palette (Ctrl-K) over every page title/heading and the in-page find (Ctrl-F). Default false (single root), true in books mode.
home string The page the Home button opens, relative to base. Default 'index.md'. In books mode Home is the first book's home (per-book home override).
dark boolean Force the dark/light render palette. Omit to auto-detect from the active theme; call reload after app.setTheme(...) to repaint.
onNavigate function onNavigate(info) after each navigation: { title, path, canBack, canForward }.
openExternal function openExternal(url) for http/mailto/… links. Default opens the system handler (sw.sys.open).

Methods

Method Description
go(target) Navigate to a page (path relative to base, or absolute, with an optional #anchor).
back() / forward() Move through history.
reload() Re-render the current page (retheme + repaint, scroll preserved).
renderString(md) Render a Markdown string directly, no navigation or history.
openSearch() / openFind() Open the quick-open palette / in-page find (no-op unless search).
help(query) Contextual help: jump to a widget/property's docs by semantic query — { widget, option } or "Widget" / "Widget#option" — without knowing the docs layout. Resolves by the api/<WidgetType>.md convention across the books (an apiRef book wins ties). Returns 'jumped' (one confident page), 'listed' (several — opens the palette as a candidate list), or 'missed' (none — fuzzy fallback).
reveal() Bring the viewer's window to the front (deiconify + raise + focus) — call alongside help() from a host that docks MarkView in its own toplevel.

Contextual help

A host that embeds MarkView (for example the Designer) can wire fast, context-sensitive help: select a widget and call help({ widget }); focus a property field and call help({ widget, option }). Because the query is semantic — widget and option names the host already owns from sw.reflect — the host never encodes file paths. The Player publishes its own documentation root as sw.app.docsBase; use it as an apiRef book so the corpus always matches the running Player.

See also