V1.0.9

DITA Viewer v1.0.9

321 commits since V1.0.8 · August 19 → October 2, 2026

---

Highlights

Content reuse by key (conkeyref)

conkeyref="brand/phrase" now pulls in the referenced content in every view — topic preview, Book, Docsite, map preview, and Git compare. Key resolution honours the selected key context map; undefined keys fall back to conref per the DITA spec; cycles are detected and terminated.

CJK spacing around English key values

When a keyref resolves to Latin text next to Chinese characters (打开ABC), a space is inserted automatically — both in the preview and in DITA-OT output via the bundled com.dita-viewer.cjk-spacing plugin. Source files are never modified; the plugin operates on DITA-OT's temporary copies and backs up every file it touches before installing.

Docsite view matures into a full reading mode

• Templates: three built-in themes (Classic Docs, Aurora, Reader) with light/dark palettes; add your own via dita-viewer.templatesDirectory.
• Keyboard navigation: sidebar tree is one Tab stop; arrow keys, Home/End, Enter/Space for expand/collapse/open.
• Back / Forward history (toolbar buttons + mouse side buttons), with scroll-position recall.
• Page-turn with ← / → keys; Ctrl+F redirected to full-book search when hovering the sidebar.
• In-place editing: map or topic edits update the page and sidebar without a reload; scroll position and search state survive.
• Per-document persistence of font size, typeface, page width, view mode, and sidebar fold state.

DITA-OT PDF export: comprehensive quality pass

A bundled customization (media/pdf-customization/) now fixes numerous org.dita.pdf2 defaults:

Issue	Fix
Latin text mixed serif/sans-serif	Override common.title and __toc__mini to serif
Fullwidth parentheses pushing English into CJK font	Extended zh_CN character set to U+FFEF
Page 1 starting at arabic 4+	Reset startPageNumbering; cover uses roman i
Blank page after every odd-page chapter	force-page-count: no-force
Bordered "Chapter N" band wraps badly in CJK	Plain single-line label, chapterLayout=BASIC
navtitle duplicating auto chapter label	Skip prefix when title already carries it
Key-only chapters counted in numbering	Only entries with content get numbered
Oversized images overflow the page	Measure + proportional shrink to column/body fit
<codeph> indistinguishable from prose	Light background for inline code
Backmatter TOC/figure-list uses roman	Arabic when positioned after body
Dismissing output dialog silently overwrites	Dismiss now cancels the export
Dark-mode white flash on site navigation	Inline <head> script sets theme before paint
Top-page links broken for sub-folder maps	Strip stray ../ from index.html hrefs

Map Checks redesigned for VS Code-native workflow

Validate / Check for Completeness and Find Unreferenced Resources now report findings in the Problems panel instead of a separate webview. The checks and quick-pick UI remain; the Explorer gets a second view no longer. Unreferenced Resources adds a smart folder/type picker with per-workspace memory.

Workspace Trust & security

• ditaOtPath and oxygenPath are now machine-scoped — a workspace cannot override them.
• DITA-OT: Transform Map…, Open in Oxygen, and Compare with Git Version are gated behind Workspace Trust.
• Virtual workspaces declared unsupported (extension reads local disk).

Git-compare rendered diff

DITA: Compare with Git Version renders both revisions through the normal DITA renderer and diffs the resulting HTML with word-level highlighting, correct HEAD/HEAD~1 resolution, older-on-left ordering, narrow-panel stacking, and recursion into full table/list structures. Chinese-aware similarity scoring included.

Key context map (Oxygen-style "context")

DITA: Select Key Context Map… picks a .ditamap that every keyref resolves against, for multi-brand/product documentation sets. Applies to previews, Go to Definition, Map Navigator, diagnostics, and export; remembered per workspace.

Wrap selection with a DITA tag

In a .dita/.ditamap editor, select text → Enter → pick a tag. The result stays well-formed; nested wrapping by pressing Enter again. Configurable via dita-viewer.wrapSelectionOnEnter.

Map Navigator improvements

• Tree rooted at the map's own <title> (with keyrefs resolved), Oxygen-style icons per element type.
• Submap rows named by the referenced map's title, not its file name.
• Expand All / Collapse All acts on the selected node; state persists across edits and restarts.
• Full-book search in Docsite mode (case/regex toggles, sticky sidebar box, highlight-on-jump).

---

Other fixes & improvements

• conkeyref with a fragment on the key's href resolves just that element.
• Multiple keys in one @keys attribute (keys="brand company") each get defined.
• Map title given by a keyref now shows the key's value.
• In-page search (Ctrl+F) matches across inline markup and multi-line source; uses CSS Custom Highlight API.
• Render error recovers automatically after the source is fixed.
• Unsaved changes in conref targets / keydef maps / book topics reflected in the preview.
• File-size cache invalidation alongside mtime (catches timestamp-preserving edits).
• Profiling highlights: block-level uses real border; li/ul/ol on pseudo-element.
• Toolbar buttons consistent height/width; SVG chevrons; Mode button stays in place.
• topichead as collapsible non-clickable group header; resource-only entries excluded from navigation.
• Chapter numbering continuous across mapref/submap boundary.
• MathML rendering (MathML Core native, <mfenced> compat shim).
• conref/conrefend range references resolved.
• indexterm chips rendered inline (including inside prolog/metadata/keywords).
• Accessibility: ARIA roles/labels on toolbar and outline tree.
• Ctrl+K V opens reading view (matching Markdown's showPreviewToSide).
• Image lightbox unified across all modes; right-click copy-to-clipboard.

Performance

• Memoized topic and book renders (keyed on actual file dependencies); off-screen book entries skipped.
• Hidden webview panels stop re-rendering.
• One file watcher shared per folder across all DITA features.
• Map tree refreshes on disk change (not only VS Code save).
• href completion no longer blocks the extension host.

Reliability & internal

• Silent catch blocks now log errors.
• Bounded imageDimensionsCache (LRU) + cleared on deactivate().
• CI runs check:l10n; full src typecheck (10 files added).
• .gitattributes pins text to LF.
• Deleted hand-written sax type shim (shadowed @types/sax).
• Full DITA user-manual fixture set under test-dita-file/manual/.
• Patched 5 dev-dependency vulnerabilities; sharp/libvips updated.
• Code refactoring: split ditaRenderUtils.ts (5057→1232 lines) into focused modules; extracted buildRenderContext shared factory.

---

Known limitations

See README → Known limitations for a full list with source references. Key items:

• conref/conkeyref chains resolve one hop only.
• CJK spacing does not cover keys inside conref-pulled content.
• External DTDs are stripped; custom domain elements have no specialization.
• Diff renders both sides against the current key map.
• Three commands gated in untrusted workspaces.
• Virtual workspaces unsupported.

---

Upgrade notes

• ditaOtPath / oxygenPath: if you set either in a workspace's .vscode/settings.json, move it to your User settings.
• CJK spacing plugin (DITA-OT): the first Transform Map… to PDF/HTML5 after upgrading asks whether to install the bundled plugin into your DITA-OT directory. A timestamped backup is written before any file is modified. Pass -Ddv.cjk.spacing.mode=off for a one-off build without it.
• Map Checks: the separate Map Checks webview is gone. Findings now appear in the Problems panel (Ctrl+Shift+M). Use DITA: Clear Map Check Results to dismiss them.

---

Full Changelog: V1.0.8...V1.0.9