# Choose the page for the job.

Use Markdown for notes and reference material. Use HTML when the page needs buttons, fields, or checkboxes you can click.

## 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.

> **Need a checklist you can tick?** Markdown task-list boxes are read-only in the preview. Use HTML when the person following the steps needs to click, type, or press a button.

## 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.

## Chapter notes

**Local files**

Supported extensions are .html, .htm, .md, and .markdown. Web addresses, localhost URLs, remote workspaces, and virtual workspaces are outside the supported scope.

**Markdown verification**

Markdown was tested on VS Code 1.141.0. The necessary preview editor appears in the source for 1.134.0, but Markdown was not tested on that version.

**A small canvas**

An HTML page about 420–640 pixels wide is a useful starting point. Keep instructions readable without scrolling sideways.

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