# Porthole manual

> Instructions and reference for Porthole 0.4.0, a VS Code extension that opens local HTML and Markdown files in floating windows.

This manual describes Porthole 0.4.0, updated 19 October 2026. It requires VS Code desktop 1.134.0 or later; the latest VS Code release is officially supported.

Local files are supported. Web addresses, localhost URLs, remote workspaces, and virtual workspaces are outside the supported scope. Porthole has been tested on macOS; Windows and Linux have not yet been tested. Outside links are experimental. Sending a command does not establish that a page rendered.

Each chapter includes its notes, version, and source reference. The complete manual contains the same five chapters.

## Chapters

- [Your first window](https://jlumbroso.github.io/porthole-docs/first-window.md): Keep a checklist, a set of instructions, or a local report beside the work. Start with a file you already have.
- [HTML and Markdown](https://jlumbroso.github.io/porthole-docs/html-and-markdown.md): Use Markdown for notes and reference material. Use HTML when the page needs buttons, fields, or checkboxes you can click.
- [Window controls](https://jlumbroso.github.io/porthole-docs/window-controls.md): Choose a size, keep the page above your other windows, and return it to the main VS Code window.
- [Terminal and agents](https://jlumbroso.github.io/porthole-docs/terminal-and-agents.md): Write the page to disk. Send its local path to VS Code with a vscode:// link.
- [Settings and help](https://jlumbroso.github.io/porthole-docs/settings-and-troubleshooting.md): Change window settings and outside-link permissions. Check the Porthole output channel when a command or link does not work.

## Complete manual

- [Full manual](https://jlumbroso.github.io/porthole-docs/manual.md): All five chapters in one Markdown file.