> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Open and Annotate Markdown, Documents, URLs, and Folders

> Open a Markdown file, plain-text data file, web page, HTML file, or folder in Plannotator, then annotate it or send edits back to your agent.

Use `plannotator annotate` to open a supported document or plain-text config file, a web page, or a folder.

## Open a Markdown or text document

```bash theme={null}
plannotator annotate README.md
plannotator annotate notes.txt
plannotator annotate config.yaml
plannotator annotate https://example.com/guide
plannotator annotate docs/
```

When you run the command directly, Plannotator starts a temporary local server, opens the annotation UI, and waits for your response. **Send Feedback** prints formatted feedback to stdout. Agent skills and commands return the same feedback to the active agent session.

Add `--gate` when the document needs an explicit approval decision:

```bash theme={null}
plannotator annotate specification.md --gate
```

## Open a folder

Pass a folder to open the file browser:

```bash theme={null}
plannotator annotate docs/
```

The browser lists the same supported local formats as direct file annotation:

* documents: `.md`, `.mdx`, and `.txt`
* plain-text config and data: `.yaml`, `.yml`, `.json`, `.jsonc`, `.json5`, `.toml`, `.ini`, `.cfg`, `.conf`, `.properties`, `.csv`, `.tsv`, `.log`, `.xml`, and `.env.example`
* HTML: `.html` and `.htm`

Plain-text config and data files keep their content unchanged and use the standard text annotation view. A bare `.env` file is excluded because it commonly contains secrets and annotation history can store content copies. Source-code extensions are excluded; use [code review](/open-source/workflows/local-changes) for them.

Only Markdown and MDX use Markdown frontmatter rules. A supported non-Markdown file that begins with `---` keeps those lines as document content.

Each local file must be 2 MiB or smaller. Select a file to annotate it, then move to another file without starting a new Plannotator session. Common generated and dependency directories, including `node_modules`, `dist`, and `build`, are skipped.

See [Annotate a Folder](/open-source/workflows/folders) for file-browser shortcuts, folder feedback, and large-folder limits.

## Follow links between local documents

In rendered Markdown, Plannotator opens relative links to `.md`, `.mdx`, `.txt`, `.html`, and `.htm` files inside the same review UI. It also opens `[[wiki-links]]`; a wiki-link without an extension resolves as a Markdown file. Relative paths are resolved from the active document.

Use the file badge or sidebar to return to the previous document. Annotations on linked documents are included when you send the review's combined feedback.

Links to a heading in another local document open the document but do not scroll to that heading. Plannotator strips the link fragment before opening the linked document. A file selected from a folder can receive per-file version history, while an ordinary document opened only through a link does not. See [Version history](/open-source/workflows/version-history).

## Open a web page

Plannotator converts web pages to Markdown before annotation. Jina Reader is used by default for public pages. URLs on localhost or private networks use a direct fetch because Jina cannot reach them.

Use direct fetch for any URL with `--no-jina`:

```bash theme={null}
plannotator annotate https://internal.example.com/guide --no-jina
```

Direct fetch converts the returned HTML with Turndown. URLs ending in `.md` or `.mdx` are read as text when the response is Markdown.

<Note>
  Plannotator annotates an imported copy of a web page, not the live page. For live-site annotation, use [App Notes in the Chrome Web Store](https://chromewebstore.google.com/detail/app-notes/lkknpieefdjpoancolcioblkpgnhpffl). The [latest GitHub release](https://github.com/plannotator/app-notes/releases/latest) provides separate Chrome and Firefox packages with checksums.
</Note>

## Edit Markdown

The Markdown editor supports two outcomes:

* For a plan, agent message, URL conversion, or other non-writable source, Plannotator sends your changes to the agent as a unified diff.
* For an eligible local Markdown, MDX, or supported plain-text file, save with `Cmd/Ctrl+S` to replace the file atomically. Plannotator confines the write to the opened source file, checks whether it changed on disk, and asks you to resolve a conflict when needed.

Saved file changes are included with submitted feedback as context so the agent knows they are already applied. Unsaved edits are not written to disk.

Local HTML has its own rendered workflow. See [Annotate HTML](/open-source/workflows/html). To change the message returned by supported agent wrappers, see [Customize Feedback](/open-source/reference/custom-feedback#plan-and-document-feedback).

Last verified on July 31, 2026, using Plannotator product commit `7cd023c`. Maintained by the Plannotator project.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.