# Your first floating window.

Keep a checklist, a set of instructions, or a local report beside the work. Start with a file you already have.

## Install Porthole.

Search for **Porthole** in VS Code’s Extensions view, or run:

```
code --install-extension jlumbroso.porthole
```

You can also visit the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=jlumbroso.porthole), find the extension on [Open VSX](https://open-vsx.org/extension/jlumbroso/porthole), or install the `.vsix` from a [GitHub release](https://github.com/jlumbroso/porthole/releases).

## Open a local file.

In VS Code, open an HTML or Markdown file: `.html`, `.htm`, `.md`, or `.markdown`. A checklist, a set of steps, or a local report makes a useful first page.

## Pop it out.

With the source file open, press **Ctrl+Alt+M** (**⌃⌥M** on macOS). You can also right-click the file in the Explorer and choose **Pop Out to Floating Window**. The editor’s title bar and the file’s tab menu offer the same action.

By default, the rendered page opens in a compact, pinned window at **420 × 640 pixels**. Tabs, breadcrumbs, and the status bar disappear. The window’s title bar remains; HTML also keeps the integrated browser’s toolbar.

[![A rendered checklist in a light floating window beside work notes in a dark VS Code editor.](https://jlumbroso.github.io/porthole-docs/assets/porthole-markdown-light.png)](https://jlumbroso.github.io/porthole-docs/assets/porthole-markdown-light.png) 

FIG. 01 — The checklist stays beside the work notes. A real Porthole capture.

## Keep working.

Switch to the editor or another application. With always-on-top enabled, the page stays in view. Save changes to an HTML file to update its rendered page; Markdown previews update as you edit.

> **A Markdown checkbox is a preview.** Task-list boxes are shown, but you cannot click them to change the file. For an interactive checklist, use an HTML page.

At first pop-out in a session, Porthole may ask whether VS Code should keep floating windows to one tab. **Keep Compact** configures that behavior, **Not Now** leaves it alone, and **Don’t Ask Again** stops future offers. You can review the setting later.

## Put it back.

Focus the floating window and press the same shortcut, or run **Porthole: Dock Back into Main Window**.

While it floats, use **Porthole: Cycle Window Size** or **Porthole: Toggle Always on Top** to adjust it. [Window controls](https://jlumbroso.github.io/porthole-docs/window-controls.html) explains the presets and opening behavior.

## Chapter notes

**What you need**

VS Code desktop 1.134.0 or later, Porthole, and a local HTML or Markdown file. The latest VS Code release is officially supported.

**Tested on macOS**

Porthole has been run on macOS. Windows and Linux have not yet been tested.

**A first-use question**

Porthole may ask whether VS Code should keep floating windows to one tab. Keep Compact, Not Now, and Don’t Ask Again let you choose.

For Porthole 0.4.0. Updated 19 October 2026. [Online chapter](https://jlumbroso.github.io/porthole-docs/index.html). [Source reference](https://github.com/jlumbroso/porthole/blob/v0.4.0/README.md).