Choose the page for the job.

A reference or an interactive page.

Porthole renders neither format itself. It brings VS Code’s existing renderer into a floating window.

Two formats, two kinds of page

HTML	Markdown
Rendered by VS Code’s integrated browser.	Rendered by VS Code’s Markdown preview.
Use buttons, text fields, and interactive checklists.	Use readable notes, instructions, and reference material.
The page’s scripts provide its behavior.	The preview is read-only. Task-list boxes cannot edit the file.
Save the file to update the rendered page.	The preview updates as you edit the file.

Write an HTML page for a small window.

Give it a useful title, such as:

<title>[my-project] Release checklist</title>

VS Code shows the page’s title in the floating window. A project name helps distinguish several pages at a glance.

Keep the page readable at about 420–640 pixels wide. Let paragraphs wrap, keep buttons large enough to use, and make long commands scroll within their own block.

A page can use its own localStorage to remember checklist state when the same file is reopened. The page supplies that behavior; Porthole does not add it.

Choose Markdown colors.

porthole.markdown.colorScheme accepts three values:

• auto follows VS Code’s theme. This is the default.
• light gives the Markdown page light colors.
• dark gives it dark colors.

The colors follow the file. While it is popped out, every preview of that file uses the chosen scheme, including a preview docked in the main window. Previews of other files keep following VS Code’s theme. Code blocks retain VS Code’s syntax colors.

Start from the local file.

Porthole opens local HTML and Markdown files. It does not yet pop out a page already open in a browser tab, a web address, or a localhost URL. Remote and virtual workspaces are outside the supported scope.

To bring a page forward again, pop out the same file. Porthole finds its existing floating window instead of opening another.