Feature Discussion: Live Preview with Forward/Inverse Search and Document Outline

[saustinp]

Feature Discussion: Live Preview with Forward/Inverse Search and Document Outline

Summary

This discussion presents a prototype implementation of LaTeX Workshop-style live preview and source navigation features for the pretext-tools VS Code extension. The motivation for this work arose from porting an academic research paper from LaTeX to PreTeXt, during which the absence of in-editor preview and source-preview synchronization became apparent. The features described below are intended to complement the existing functionality in pretext-tools without modifying any current behavior.

This post is a request for feedback on whether these features align with the project's direction, and whether the implementation approach is suitable for potential upstream integration. All code is available for review in a working fork.

Working fork: https://github.com/saustinp/pretext-tools

---

Features Implemented

1. Live Side-by-Side Preview

A new command (Ctrl+Alt+L / Cmd+Alt+L) opens the compiled HTML/PDF/EPUB/Braille output in a VS Code WebviewPanel adjacent to the source editor.

HTML Live Preview

PDF Live Preview

Toolbar provides Refresh and Open in Browser controls:

Implementation details:

• The extension invokes pretext view --no-launch to start the local preview server without opening an external browser
• The output is displayed within an embedded iframe in a VS Code panel
• A toolbar provides Refresh and Open in Browser controls
• Server lifecycle management includes --restart-server on startup and --stop-server on panel close to prevent orphaned processes
• If no compiled output exists, the extension automatically runs pretext build <target> before starting the server, with build progress reported in the PreTeXt output channel
• The build process is tolerant of partial failures (e.g., missing optional tools such as Sage); if HTML files are generated despite non-zero exit codes, the preview proceeds

2. Auto-Rebuild on Save

When the live preview is active, saving any .ptx or .xml file triggers an automatic rebuild followed by a preview refresh.

• This behavior is configurable via the pretext-tools.livePreview.autoCompile setting (default: enabled)
• A one-second debounce prevents redundant builds during rapid successive saves
• Build status is reflected in the VS Code status bar

3. Inverse Search (Preview to Source)

Clicking on any element in the HTML preview navigates the editor to the corresponding location in the source file.

Hovering over an element turns the bounding box blue:

Clicking anywhere inside the bounding box turns the border orange and triggers the inverse search functionality:

Implementation:

• A JavaScript snippet is injected into the built HTML files (appended before </body>) that attaches click and hover handlers to all elements with id attributes
• Hovering displays a blue outline to indicate clickable regions
• Clicking transmits the element's id to the extension via window.parent.postMessage (cross-origin compatible)
• The extension resolves the HTML element ID to a source location through a series of strategies applied in order:
  1. Direct ID match against xml:id and label attributes
  2. Suffix stripping to handle PreTeXt's auto-generated child element IDs (e.g., section-foo-3-1 is progressively reduced to section-foo-3, section-foo)
  3. Prefix stripping to accommodate label attributes that prepend structural prefixes (e.g., section-) to the xml:id
  4. Text-based refinement within the matched block, using distinctive words extracted from the clicked paragraph to locate the exact source line
  5. Pure text fallback for deeply auto-generated IDs with no source counterpart, searching the entire file by content

Edge cases addressed:

• Chunked HTML output where each section resides in a separate file
• Deeply nested structures such as corollaries, proofs, and objectives
• Elements whose label attribute differs from their xml:id
• Paragraphs within list items
• Both .ptx and .xml source file extensions

4. Forward Search (Source to Preview)

Pressing Ctrl+Alt+J / Cmd+Alt+J scrolls the preview to the location corresponding to the editor cursor.

Implementation:

• Approximately 300 characters of plain text following the cursor position are extracted (with XML tags removed)
• Distinctive words (five or more characters) are identified
• All HTML output files are searched for a matching word sequence
• The nearest preceding HTML element with an id attribute is identified
• The preview navigates to the appropriate HTML page (supporting chunked output) and scrolls to the identified element

Text-based matching was selected over paragraph counting because PreTeXt's HTML ID numbering scheme is structurally complex and varies with nesting depth and element type. Text matching provides more reliable results across diverse document structures.

5. Document Outline

A PreTeXt icon is added to the VS Code Activity Bar, providing a hierarchical document structure view in the sidebar.

Displayed elements:

• Article and Book root elements
• Chapters, Sections, Subsections, and Subsubsections
• Front Matter, Back Matter, and Appendices
• References
• Named <paragraphs> blocks (e.g., Acknowledgments)

Excluded elements (to maintain clarity):

• Figures, tables, and equations
• Untitled paragraphs
• Non-structural elements

Behavior:

• Each item is clickable and navigates to the corresponding source line
• The outline updates automatically on document edits and file switches
• A refresh control is available in the panel header
• Both .ptx and .xml files are supported

6. Multi-Format Live View

The live preview command supports all PreTeXt output targets:

Target	Behavior
HTML	Embedded WebviewPanel with forward/inverse search
PDF	Opened in VS Code's PDF viewer (requires an extension such as vscode-pdf)
Braille	Opened as a .brf text file in the VS Code editor
EPUB	Opened in VS Code if an EPUB reader extension is detected; otherwise opened with the system default application

All targets automatically build if the output file does not yet exist, with progress displayed in the output channel.

7. Integration with Existing View Methods

"Live Preview (side-by-side)" is added as an option in both the Ctrl+Alt+V quick-pick dialog and the pretext-tools.viewMethod configuration dropdown, alongside the existing "Use PreTeXt's view command" and "Use CodeChat" options.

---

Scope of Changes

These features are entirely additive. No existing functionality has been modified:

• All existing commands, keybindings, snippets, and schema validation remain unchanged
• The Visual Editor and LSP server are unaffected
• The existing external browser view (Ctrl+Alt+V) continues to function as before
• No new npm dependencies have been introduced; all features use VS Code's built-in APIs and the existing child_process patterns in the codebase

---

Technical Summary

Files added:

• packages/vscode-extension/src/livePreview.ts (~1100 lines)
• packages/vscode-extension/src/documentOutline.ts (~400 lines)

Files modified:

• packages/vscode-extension/src/extension.ts — Command registration (+8 lines)
• packages/vscode-extension/src/commands/view.ts — "Live Preview" added to view method picker
• packages/vscode-extension/package.json — Commands, keybindings, view container, and configuration additions
• packages/format/index.js — Corrected a broken symlink that prevented building from source

New keybindings:

Keybinding	Command
Ctrl+Alt+L / Cmd+Alt+L	Open Live Preview
Ctrl+Alt+J / Cmd+Alt+J	Forward Search

New configuration options:

• pretext-tools.livePreview.autoCompile (boolean, default: true)
• "Live Preview" added to the pretext-tools.viewMethod enumeration

---

Testing

The implementation has been tested with the following configurations:

• Custom article (single-page, AIAA conference paper format): All features functional
• PreTeXt sample-article (283 pages, chunked HTML, complex structure including proofs, corollaries, objectives, and reading questions): Forward search, inverse search, and document outline all functional; auto-build handles partial failures gracefully
• EPUB viewer: Tested with the epub-reader-vscode extension
• PDF viewer: Tested with the vscode-pdf extension
• Platform: Linux (Ubuntu 24.04), VS Code, Node.js 22

---

Known Limitations

• Forward/inverse search is HTML-only. Source-to-preview and preview-to-source navigation is available only for the HTML live preview. PDF, braille, and EPUB targets open as static files without navigation capabilities.
• Forward search precision. The search typically resolves to the paragraph level but may fall back to the enclosing section for very short paragraphs or elements with few distinctive prose words.
• Math-heavy paragraphs. Forward search may default to section-level navigation for paragraphs consisting primarily of mathematical content, since LaTeX expressions in the source do not correspond to the rendered text in HTML. Inverse search remains functional for these paragraphs.
• Knowl popups. Inverse search does not operate within dynamically generated knowl popups (expandable cross-reference boxes). The knowl's built-in navigation link provides an alternative path to the referenced element.
• Multi-page HTML navigation. When the HTML output is split across multiple pages (chunking level 1 or higher), forward search to a different page requires a full page reload rather than an in-page scroll.

---

Questions for Discussion

1. Feature alignment. Does this direction complement the project's existing roadmap? Given that CodeChat integration already provides some preview capability, would a built-in alternative be welcome?
2. Architecture. The live preview implementation resides in a single ~1100-line module. Would the maintainers prefer this decomposed into smaller, focused modules?
3. Script injection. The inverse search mechanism injects a <script> tag into the built HTML files. Is this approach acceptable, or would an alternative mechanism be preferred?
4. Document outline scope. The outline currently displays only section-level headings. Would it be desirable to include figures, tables, and theorem-like environments, perhaps behind a configuration toggle?

Feedback and suggestions are welcome. Thank you for the excellent work on this project.

[saustinp]

There has been some discussion about existing support for the CodeChat renderer and how this compares to my proposed implementation. This is a fair question and deserves a thorough answer, because on the surface the pitches sound similar: "live HTML preview of your PreTeXt document in a VS Code side panel." I'm confident the overlap is narrower than it looks, and the two tools are complementary rather than redundant. I want to lay out the differences carefully, with line-level citations to CodeChat's source, so this discussion can proceed on accurate footing.

What CodeChat does for PreTeXt, specifically

Credit where it's due: CodeChat is not a generic HTML previewer that happens to tolerate PreTeXt. It has a real ProjectTypeEnum.PreTeXt code path in its renderer (renderer.py L243–245). When a PreTeXt project is configured, CodeChat:

• reads a .mapping.json file emitted during the build,
• extracts the first xml:id from the currently-open .ptx file (renderer.py L311–319),
• uses that xml:id to look up which chunked HTML file to display in the side panel (renderer.py L367–383),
• watches the filesystem and rebuilds on save.

That's a genuinely useful integration and it was clearly designed with PreTeXt's chunked-HTML output in mind. I am not dismissing it.

However, that is the extent of CodeChat's PreTeXt-specific functionality. The VS Code extension source contains no cursor, selection, scroll, or sync handling code — the xml:id mapping is used only for initially selecting the right chunked file when the active editor changes, not for within-file navigation. And the preview architecture is unambiguously HTML-only: the extension declares a single webview_panel: vscode.WebviewPanel (extension.ts L66) whose content is set via direct webview_panel.webview.html = ... assignment (extension.ts L168, L291). There is no PDF renderer path, no EPUB handling, no binary-format display — the preview is a string of HTML dropped into a webview, and that's by design.

Side-by-side comparison

Feature	pretext view (CLI)	CodeChat	Feature under consideration
In-editor preview panel (no external browser)	❌ opens system browser	✅ side panel	✅ side panel
Extra installs beyond pretext-tools	✅ none (ships with PreTeXt-CLI)	❌ pip install CodeChat_Server and a second VS Code extension	✅ none
Per-project configuration file required	✅ none	❌ hand-written codechat_config.yaml	✅ none — reads project.ptx
Auto-rebuild on save	❌	✅ (via internal filesystem watcher)	✅ (via VS Code's onDidSaveTextDocument, debounced)
Forward search (cursor in source → scroll preview)	❌	❌	✅
Inverse search (click preview → jump to source)	❌	❌	✅
Document outline sidebar	❌	❌	✅
PDF preview	❌	❌ (HTML-only webview architecture)	✅ (via vscode-pdf)
EPUB preview	❌	❌	✅ (via vamsi-hari.epub-reader-vscode or system viewer)
Braille preview (.brf)	❌	❌	✅ (opens in editor)
Background processes to clean up	✅ none	❌ persistent Python server (CodeChat_Server stop to kill)	✅ tied to panel lifecycle
Works with any target declared in project.ptx	✅	⚠️ only the one hard-coded in the YAML	✅
Maintenance activity	✅ ongoing	⚠️ low — last substantive commit 2024‑05‑08 (CherryPy workaround), last PreTeXt-specific change 2023‑11‑08	—

Some important rows are forward/inverse search and multi-format preview. Those are the features that motivated this prototype in the first place — the LaTeX Workshop experience that authors coming from LaTeX explicitly ask for. Neither exists in CodeChat or in pretext view. The PDF row is also significant: my own primary target as an author is PDF (the LaTeX output going to a journal), and no HTML-only previewer addresses that workflow.

Why the installation and configuration burden matters

I want to spend a moment on the "extra installs" row because I think it's easy to dismiss as a minor detail, but for the target audience of pretext-tools it is one of the biggest practical differences. The two extra installs aren't trivial — they're friction at exactly the wrong moment, when a new user is trying to get a preview working for the first time:

1. pip install CodeChat_Server assumes the user has a working Python environment outside whatever environment PreTeXt itself runs in, and that the installed binary lands somewhere on PATH. On Windows and macOS this is often a mess: pip install without --user may fail on externally-managed Python installs, --user may place binaries somewhere the shell doesn't see, and users running PreTeXt via pipx or a project-local venv end up with two Python environments to reconcile. This is the single most common support issue I've seen in help channels for any Python-tooling extension.

2. A second VS Code extension must be discovered and installed separately. pretext-tools does not bundle CodeChat.codechat, nor does it prompt the user to install it. The integration in commands/view.ts is a conditional if (extensions.getExtension("CodeChat.codechat")) check that silently hides the menu option when CodeChat isn't present. A user reading the pretext-tools README line "Support for the CodeChat extension to view output" has no indication that they're about to begin a multi-step install.

3. Every new PreTeXt project needs a hand-written codechat_config.yaml at the project root to get a rendered preview. Without it, CodeChat has no project-mode handling for .ptx files (it returns "No converter found for this file"), and for .xml files it falls back to a single-file syntax-highlighting view that shows raw XML source rather than the rendered textbook. CodeChat ships no template or generator for this file — the author has to write it from scratch. If the user's project.ptx changes — a target is renamed, chunking level changes, output directory moves — the YAML breaks silently and the preview stops matching the source. New authors are unlikely to know that codechat_config.yaml even exists, let alone what values to put in it.

4. A persistent background Python server continues running after VS Code closes unless the user remembers to run CodeChat_Server stop manually. This is minor, but it's the kind of thing that accumulates frustration over time.

By contrast, the approach in this PR is zero-install beyond pretext-tools itself. The live preview calls pretext view --no-launch --restart-server, which is already part of PreTeXt-CLI — itself a hard dependency of the extension. The webview is built into VS Code. The server process is tied to the panel lifecycle and cleaned up on dispose. No configuration file is needed — targets are enumerated from project.ptx. A first-time user opens a PreTeXt project, presses Ctrl+Alt+L, and it works.

That is a meaningful difference for the audience pretext-tools serves. "It just works in the extension I already installed" versus "install two more things and write a YAML file" could, in my experience, be the difference between a feature people actually use and a feature that exists on paper.

In summary

CodeChat is a thoughtful, general-purpose literate-programming previewer with real (if narrow) PreTeXt awareness. It solves one version of the preview problem well: show me the rendered HTML of the chunk I'm currently editing, and rebuild when I save. For authors who are already comfortable with its install model and only work in HTML, it's a reasonable tool.

What this PR adds is a different thing: a PreTeXt-native editing experience with bidirectional source↔preview navigation, a document outline, multi-format support (HTML/PDF/EPUB/braille), and zero additional installation. These are the features that bring the extension closer to the LaTeX Workshop workflow that many PreTeXt authors — especially those porting from LaTeX — explicitly ask for. None of them overlap with what CodeChat provides, and for the majority of users who are not going to install a Python server to preview their textbook, this would be the preview path they actually use.

I'm very open to discussion on implementation details, scope, or whether any of this should be gated behind settings for users who prefer the existing options.

[oscarlevin]

This is incredibly exciting, and something I've hoped we could add for a long time. I haven't had time to dive into this yet, but will very soon. Thanks for getting this going.

[saustinp]

Thank you! I will plan to attend the pretext drop-in hours tomorrow and hope to discuss with you further.