---
id: "arquivos-markdown"
titulo: "Markdown: modes, formatting and notes"
resumo: "Create a new Markdown file, switch between source, rich and preview, use rich editing, and annotate a document for review."
idioma: "en"
tipo: "guia"
categoria: "arquivos-git"
aplicavelDesde: "0.0.16"
capabilities: ["editor.markdown.views", "editor.markdown.richFormatting", "editor.newMarkdown.untitled", "editor.untitledRename", "review.markdown.notes"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/en/ferramentas/arquivos/markdown/"
fonte: "pt-br/ferramentas/arquivos/markdown.md"
caminhoPublico: "docs/publica/en/ferramentas/arquivos/markdown.md"
hashFonte: "sha256:eb4a2c85a0ab78a4c9c5e4e8de0dbcd1716168075254804e11c6d571175d0e36"
hashDestaPagina: "sha256:bba43907f3079726da92c463e311462b0124ade8922aa999aef14878d26c1c75"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/ferramentas/arquivos/markdown.md fonteHash=sha256:eb4a2c85a0ab78a4c9c5e4e8de0dbcd1716168075254804e11c6d571175d0e36 estado=atual -->

## Create a new Markdown file

Two paths:

- **Tab bar → new tab → Markdown**
- **Quick commands → new Markdown file**

Both open a **template picker**: choose a template and the file is born from it.

How this works underneath — and what you need to know:

- **The file is written to disk at creation**, and renamed afterwards. It exists before you type anything.
- **Closing without editing removes the placeholder**: if you created it and wrote nothing, the file does not stay behind.
- A template **with real content** changes that behavior: in that case the file is not removed when closed without edits.

## Save or rename a new file

The save dialog asks for **name and folder**:

- The name **cannot be empty** and cannot contain slashes.
- **The folder must be inside the workspace.**
- Validation errors appear in the dialog itself, not as a loose notice.
- The folder can be chosen in the system picker.

## The three Markdown modes

| Mode | What it does |
|---|---|
| **Source** | Shows the Markdown text as it is |
| **Rich** | Editing with formatting applied |
| **Preview** | Renders the result, without editing |

- **Preview to the side** opens the render in a separate panel, keeping the text in view.
- **Table of contents** is available in the **rich** and **preview** modes — not in source mode.
- **Show/hide front matter** toggles the display of the document's header.
- **Export as PDF** generates a PDF of the document. The export becomes **unavailable when there is no rendered content** to export — that is, in source mode there is nothing to export.

> **"Changes" mode is mutually exclusive with the Markdown modes at render time.** Choosing Changes leaves Markdown mode; going back to Markdown leaves Changes.

## Rich editing

In rich mode, the document is edited with formatting applied, and the surface offers:

- **Formatting bar** — bold, italic, headings, lists, table, image and link.
- **Command menu** — commands fired from the bar.
- **Emoji menu**.
- **Link balloon** — edit, open or remove the link under the cursor.
- **Internal document link menu** — points to another document instead of an external URL.
- **In-document search bar**.

> **The same formatting bar appears in the Canvas note.** There it belongs to the Canvas domain; this page covers its use inside the file editor.

## Review notes

Review notes are annotations **anchored to passages of text** in the document — a comment stuck to the sentence, not to the file.

- The **notes rail** shows and hides the notes, with a toggle button.
- Each note is a **card** that can be **copied, edited and deleted**.
- Notes can be **sent to the agent** through their own menu.
- Notes require the **rich mode with annotations enabled**.

**Important limit:** notes are anchored to passages, and positioning depends on the document's layout. **Text changes can shift the anchors** — if you edit a lot after annotating, check whether each note still points at the right passage.

## Limits

- **Export as PDF** depends on there being a rendered document.
- **Table of contents** does not exist in source mode.
- **Review notes** require rich mode with annotations enabled and can shift when the text changes.

## Related

- [The editor](/docs/en/ferramentas/arquivos/editor/)