|
| 1 | +## Overview |
| 2 | + |
| 3 | +The [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) includes a visual markdown editor that supports all of Quarto's markdown syntax including tables, citations, cross-references, footnotes, divs/spans, definition lists, attributes, raw HTML/TeX, and more: |
| 4 | + |
| 5 | +{.border width="609"} |
| 6 | + |
| 7 | +You can switch between visual and source mode at any time and can even edit documents concurrently in both modes. To switch between visual and source mode: |
| 8 | + |
| 9 | +1. Use the <kbd>⇧⌘ F4</kbd> keyboard shortcut. |
| 10 | + |
| 11 | +2. Use the context menu from anywhere in a document: |
| 12 | + |
| 13 | + {.border width="609"} |
| 14 | + |
| 15 | +3. Use the **Edit in Visual Mode** and **Edit in Source Mode** commands: |
| 16 | + |
| 17 | + {.border width="609"} |
| 18 | + |
| 19 | +4. Use the editor menu: |
| 20 | + |
| 21 | + {.border width="609"} |
| 22 | + |
| 23 | +You can also right click a `.qmd` document in the file explorer and select the **Open With...** command, which will prompt you for the editor to open the file with: |
| 24 | + |
| 25 | +{.border width="609"} |
| 26 | + |
| 27 | +Note that this menu also provides an option to configure the default editor for `.qmd` files: use this if you want to primarily edit in visual mode and occasionally switch to source mode. |
| 28 | + |
| 29 | +## Keyboard Shortcuts |
| 30 | + |
| 31 | +Visual mode supports both traditional keyboard shortcuts (e.g. <kbd>⌘ B</kbd> for bold) as well as markdown shortcuts (using markdown syntax directly). For example, enclose `**bold**` text in asterisks or type `##` and press space to create a second level heading. |
| 32 | + |
| 33 | +Here are the available keyboard and markdown shortcuts: |
| 34 | + |
| 35 | +| Command | Keyboard Shortcut | Markdown Shortcut | |
| 36 | +|--------------------|:------------------:|:---------------------:| |
| 37 | +| Bold | <kbd>⌘ B</kbd> | `**bold**` | |
| 38 | +| Italic | <kbd>⌘ I</kbd> | `*italic*` | |
| 39 | +| Code | <kbd>⌘ D</kbd> | `` `code` `` | |
| 40 | +| Strikeout | | `~~strike~~` | |
| 41 | +| Subscript | | `~sub~` | |
| 42 | +| Superscript | | `^super^` | |
| 43 | +| Heading 1 | <kbd>⌥⌘ 1</kbd> | `#` | |
| 44 | +| Heading 2 | <kbd>⌥⌘ 2</kbd> | `##` | |
| 45 | +| Heading 3 | <kbd>⌥⌘ 3</kbd> | `###` | |
| 46 | +| Heading Attributes | | `{#id .class}` | |
| 47 | +| Link | <kbd>⌘ K</kbd> | `<href>` | |
| 48 | +| Blockquote | | `>` | |
| 49 | +| Code Block | <kbd>⇧⌘ \\</kbd> | ```` ``` ```` | |
| 50 | +| Code Cell | <kbd>⌥⌘ I</kbd> | ```` ```{python} ```` | |
| 51 | +| Raw Block | | ```` ```{=html} ```` | |
| 52 | +| Div | | `:::` | |
| 53 | +| Bullet List | | `-` | |
| 54 | +| Ordered List | | `1.` | |
| 55 | +| Tight List | <kbd>⌥⌘ 9</kbd> | | |
| 56 | +| List Check | | `[x]` | |
| 57 | +| Emoji | | `:smile:` | |
| 58 | +| Definition | | `:` | |
| 59 | +| Non-Breaking Space | <kbd>⌃ Space</kbd> | | |
| 60 | +| Hard Line Break | <kbd>⇧ Enter</kbd> | | |
| 61 | +| Paragraph | <kbd>⌥⌘ 0</kbd> | | |
| 62 | +| Image | <kbd>⇧⌘ I</kbd> | | |
| 63 | +| Footnote | <kbd>⇧⌘ F7</kbd> | | |
| 64 | +| Citation | <kbd>⇧⌘ F8</kbd> | `[@` | |
| 65 | +| Table | <kbd>⌥⌘ T</kbd> | | |
| 66 | +| Editing Comment | <kbd>⇧⌘ C</kbd> | | |
| 67 | +| Select All | <kbd>⌘ A</kbd> | | |
| 68 | +| Clear Formatting | <kbd>⌘ \\</kbd> | | |
| 69 | +| Edit Attributes | <kbd>F4</kbd> | | |
| 70 | + |
| 71 | +::: {.callout-tip appearance="simple"} |
| 72 | +For markdown shortcuts, if you didn't intend to use a shortcut and want to reverse its effect, just press the backspace key. |
| 73 | +::: |
| 74 | + |
| 75 | +## Insert Anything |
| 76 | + |
| 77 | +You can also use the catch-all <kbd>⌘ /</kbd> shortcut to insert just about anything. Just execute the shortcut then type what you want to insert. For example: |
| 78 | + |
| 79 | +::: {layout-ncol="2"} |
| 80 | +{fig-alt="There is a line of text (with a cursor at the end) where someone has typed '/lis'. There is a drop-down menu underneath this with options for 'Bullet List', 'Numbered List', and 'Definition List' arranged vertically. The title of each item is bolded, has a small icon to the left, and a small description in lighter gray text underneath it." width="400"} |
| 81 | + |
| 82 | +{fig-alt="There is a line of text (with a cursor at the end) where someone has typed '/ma'. There is a drop-down menu underneath this with options for 'Inline Math', 'Display Math', and 'Image...' arranged vertically. The title of each item is bolded, has a small icon to the left, and a small description in lighter gray text underneath it." width="400"} |
| 83 | +::: |
| 84 | + |
| 85 | +If you are at the beginning of a line (as displayed above), you can also enter plain `/` to invoke the shortcut. |
| 86 | + |
| 87 | +## Editor Toolbar |
| 88 | + |
| 89 | +The editor toolbar includes buttons for the most commonly used formatting commands: |
| 90 | + |
| 91 | +{.border width="609"} |
| 92 | + |
| 93 | +Additional commands are available on the **Format**, **Insert**, and **Table** menus: |
| 94 | + |
| 95 | +| Format | Insert | Table | |
| 96 | +|------------------------|------------------------|------------------------| |
| 97 | +| {.border fig-alt="The contents of the Format drop down menu."} | {.border fig-alt="The contents of the Insert drop down menu."} | {.border fig-alt="The contents of the Table drop down menu."} | |
| 98 | + |
| 99 | +## Editor Options |
| 100 | + |
| 101 | +There are a variety of {{< meta tool.name >}} options available to configure the behavior of the visual editor. You can locate these options by filtering on `quarto.visualEditor` in the settings pane: |
| 102 | + |
| 103 | +{.border width="609"} |
| 104 | + |
| 105 | +Options enable configuration of appearance (font size, content width, etc.), markdown output (e.g. column wrapping), spell checking, and default spacing for lists. |
| 106 | + |
| 107 | +## Zotero Citations |
| 108 | + |
| 109 | +[Zotero](https://zotero.org) is a popular free and open source reference manager. The Quarto visual editor integrates directly with Zotero, enabling you to use the **Insert Citation** command to use references from your Zotero libraries: |
| 110 | + |
| 111 | +{.illustration fig-alt="The 'Insert Citation' dialog. The 'My Library' option is selected. The search bar at the top of the right section is empty, but the search results section is filled with the contents of a Zotero reference manager library. Each of the search result icons has a small 'Z' on the bottom right to indicate that the result comes from a Zotero library."} |
| 112 | + |
| 113 | +Zotero references will also show up automatically in visual editor completions: |
| 114 | + |
| 115 | +<img src="/docs/visual-editor/images/visual-editing-citation-completions.png" width="426" fig-alt="Someone has typed '@' in the Visual Editor. In light gray to the right of the '@' is a magnifying glass followed by the text 'or DOI'. Underneath this is a pop-up menu showing available citations. Each citation has a title of the form '@citation' in black, the title of the cited material in gray underneath it, an icon to the left, and the reference to the right in gray. Some of the icons have a small red 'Z' on the bottom right corner, indicating that the corresponding reference comes from a Zotero library."/> |
| 116 | + |
| 117 | +Items from Zotero will appear alongside items from your bibliography with a small "Z" logo juxtaposed over them. If you insert a citation from Zotero that isn't already in your bibliography then it will be automatically added to the bibliography. |
| 118 | + |
| 119 | +If you are running both {{< meta tool.name >}} and Zotero on your desktop, then no additional configuration is required for connecting to your Zotero library. If however you [are using VS Code in a web browser and/or]{.content-hidden unless-meta="tool.is_vscode"} want to access your Zotero library over the web, then a few more steps are required (see the [Zotero Web API](#zotero-web-api) section for details). |
| 120 | + |
| 121 | +### Group Libraries {#group-libraries} |
| 122 | + |
| 123 | +[Zotero Groups](https://www.zotero.org/support/groups) provide a powerful way to share collections with a class or work closely with colleagues on a project. By default, Zotero Group Libraries are not included in the **Insert Citation** dialog or citation completions. However, you can use the *Quarto \> Zotero: Group Libraries* option to activate one or more group libraries (either globally, or per-workspace): |
| 124 | + |
| 125 | +{.illustration width="563"} |
| 126 | + |
| 127 | +After you've added a group library to the list, a sync will be performed and you should see the library in the **Insert Citation** dialog. If you don't, double check the exact spelling of the group library name you are configuring (you may even want to copy and paste it from Zotero so you are certain to get it right). |
| 128 | + |
| 129 | +### Zotero Web API {#zotero-web-api} |
| 130 | + |
| 131 | +If you [are using VS Code in a web browser and/or]{.content-hidden unless-meta="tool.is_vscode"} don't have Zotero installed locally, you can still access your Zotero library using the Zotero Web API (assuming you have a Zotero web account and have synced your libraries to your account). |
| 132 | + |
| 133 | +::: {.callout-tip appearance="simple"} |
| 134 | +If you are running {{< meta tool.name >}} on your desktop it's generally easier to also run Zotero on your desktop and access your library locally. That said, it is possible to access Zotero web libraries from {{< meta tool.name >}} on the desktop if you prefer that configuration. |
| 135 | +::: |
| 136 | + |
| 137 | +#### API Access Key |
| 138 | + |
| 139 | +Zotero integration uses the Zotero Web API, so the first step is to [create a Zotero account](https://www.zotero.org/user/register) and then configure Zotero to sync its data to your account. You can do this using the **Sync** tab of the Zotero preferences: |
| 140 | + |
| 141 | +{.illustration fig-alt="The Sync tab of Zotero preferences." width="675"} |
| 142 | + |
| 143 | +Once you've configured your library to sync, you need to [create a Zotero API Key](https://www.zotero.org/settings/keys/new): |
| 144 | + |
| 145 | +{.illustration fig-alt="The 'New Private Key' section of Zotero. The 'Allow library access' option is selected." width="675"} |
| 146 | + |
| 147 | +Follow the instructions to create a new access key. Note that if you want to use [Group Libraries](#group-libraries), you should change the default to provide read-only access to groups (as illustrated above). |
| 148 | + |
| 149 | +Be sure to **record your key** after generating it (i.e. copy it to the clipboard and/or save it somewhere more permanent) as you won't be able to view it again after you navigate away. |
| 150 | + |
| 151 | +#### Library Configuration |
| 152 | + |
| 153 | +Finally, go to Zotero settings and specify that you'd like to use your `web` Zotero library rather than a local one: |
| 154 | + |
| 155 | +{.border} |
| 156 | + |
| 157 | +You'll then be promoted to enter your Zotero Web API Key: |
| 158 | + |
| 159 | +{.illustration width="601"} |
| 160 | + |
| 161 | +After you provide your API key and it is validated, an initial sync of your Zotero libraries is performed. After this, you are ready to start inserting citations from Zotero. |
| 162 | + |
| 163 | +::: callout-note |
| 164 | +If you need to change your Zotero API key, you can always execute the **Quarto: Zotero - Connect Web Library** command. To force a sync of your web library, execute the **Quarto: Zotero - Sync Web Library** command (note that your web library is synced automatically so it is unlikely you'll need to use this command explicitly). |
| 165 | +::: |
| 166 | + |
| 167 | +## Markdown Output |
| 168 | + |
| 169 | +The Quarto visual editor generates markdown using Pandoc. This means that in some cases your markdown will be *rewritten* to conform to standard Pandoc idioms. For example, Pandoc inserts 3 spaces after list bullets and automatically escapes characters that might be used for markdown syntax. |
| 170 | + |
| 171 | +Here is a list of conventions for Pandoc generated markdown that might differ from your own markdown writing style: |
| 172 | + |
| 173 | +- `*text*` is used in preference to `_text_` |
| 174 | +- Backtick code blocks are written as ```` ``` {.md} ```` rather than ```` ```md ```` |
| 175 | +- Backtick code blocks with no attributes are rendered as 4-space indented code blocks |
| 176 | +- Horizontal rules are written as dashes spanning the full width of the document |
| 177 | +- Plain links are written as `<https://yihui.org>` rather than `https://yihui.org` |
| 178 | +- Bullet and numbered lists use additional leading spaces before list item content |
| 179 | +- The blockquote character (`>`) is included on each new line of a blockquote |
| 180 | +- Table captions are written below rather than above tables |
| 181 | +- Multiline HTML and TeX blocks use the explicit raw attribute (e.g. ```` ```{=tex} ````) |
| 182 | +- Inline footnotes are replaced with footnotes immediately below the paragraph |
| 183 | +- Nested divs use `:::` at all levels so long as their attributes are distinct |
| 184 | +- Unnumbered sections are designated with `{.unnumbered}` rather than `{-}` |
| 185 | +- Characters used for markdown syntax (e.g. `*`, `_`, or `#`) are always escaped |
| 186 | + |
| 187 | +While some of this behavior might be bothersome at first, if you decide that visual editing mode is useful for your workflow it's probably best to just adapt to writing your own markdown the same way that Pandoc does. |
| 188 | + |
| 189 | +### Writer Options |
| 190 | + |
| 191 | +Some aspects of markdown output can be customized via global, project, or file-level options, including: |
| 192 | + |
| 193 | +- How to wrap / break lines (fixed column, sentence-per-line, etc.). |
| 194 | +- Where to write footnotes (below the current paragraph or section, or at the end of the document). |
| 195 | +- Whether to write inline or reference style links. |
| 196 | + |
| 197 | +You can specify these options in one of two ways: |
| 198 | + |
| 199 | +1. As a global or per-workspace {{< meta tool.name >}} option (you can find the options that affect markdown output by filtering on `quarto.visualEditor.markdown`). |
| 200 | + |
| 201 | +2. Specifying them within document or project level YAML (described below). |
| 202 | + |
| 203 | +#### Line Wrapping |
| 204 | + |
| 205 | +By default, the visual editor writes Markdown with no line wrapping (paragraphs all occupy a single line). However, if you prefer to insert line breaks at a particular column (e.g. 72 or 80), or to insert a line break after each sentence, you can use the `quarto.visualEditor.markdownWrap` and `quarto.visualEditor.markdownWrapColumn` options accessible from the settings editor in {{< meta tool.name >}}. |
| 206 | + |
| 207 | +You can also set this behavior on a per-document or per-project basis via the `wrap` option. For example, to wrap lines after 72 characters you would use this: |
| 208 | + |
| 209 | +``` yaml |
| 210 | +--- |
| 211 | +editor: |
| 212 | + markdown: |
| 213 | + wrap: 72 |
| 214 | +--- |
| 215 | +``` |
| 216 | + |
| 217 | +To insert a line break after each sentence, use `wrap: sentence`. For example: |
| 218 | + |
| 219 | +``` yaml |
| 220 | +--- |
| 221 | +editor: |
| 222 | + markdown: |
| 223 | + wrap: sentence |
| 224 | +--- |
| 225 | +``` |
| 226 | + |
| 227 | +::: {.callout-note appearance="simple"} |
| 228 | +The algorithm used for sentence wrapping will handle English and Japanese text well, but may not detect the end of sentences accurately for other languages. |
| 229 | +::: |
| 230 | + |
| 231 | +If you have enabled a global line wrapping option and want to turn off wrapping for a given document, use `wrap: none`. |
| 232 | + |
| 233 | +#### References |
| 234 | + |
| 235 | +By default, references (footnotes and reference links) are written at the end of the block where their corresponding footnote appears. You can override this behavior using the `quarto.visualEditor.markdownReferences` {{< meta tool.name >}} setting or by using the `references` option within document or project YAML. |
| 236 | + |
| 237 | +For example, to write references at the end of sections rather than blocks you would use: |
| 238 | + |
| 239 | +``` yaml |
| 240 | +--- |
| 241 | +title: "My Document" |
| 242 | +editor: |
| 243 | + markdown: |
| 244 | + references: |
| 245 | + location: block |
| 246 | +--- |
| 247 | +``` |
| 248 | + |
| 249 | +Valid values for the `references` option are `block`, `section`, and `document`. |
| 250 | + |
| 251 | +If you are aggregating a set of markdown documents into a larger work, you may want to make sure that reference identifiers are unique across all of your documents (e.g. you don't want to have `[^1]` appear multiple times). You can ensure uniqueness via the `prefix` option. For example: |
| 252 | + |
| 253 | +``` yaml |
| 254 | +--- |
| 255 | +title: "My Document" |
| 256 | +editor: |
| 257 | + markdown: |
| 258 | + references: |
| 259 | + location: block |
| 260 | + prefix: "mydoc" |
| 261 | +--- |
| 262 | +``` |
| 263 | + |
| 264 | +This will result in footnotes in this document using the specified prefix (e.g. `[^mydoc-1]`), ensuring they are globally unique across the manuscript. |
| 265 | + |
| 266 | +::: {.callout-note appearance="simple"} |
| 267 | +Note that if you are within a Quarto [book](/docs/books/book-basics.qmd) project then a references `prefix` is applied automatically so no changes to `editor` options are required. |
| 268 | +::: |
| 269 | + |
| 270 | +#### Links |
| 271 | + |
| 272 | +Links are written inline by default, however they can be written as reference links (below content as with footnotes) by adding the `links: true` option to the `references` section of document or project YAML. For example: |
| 273 | + |
| 274 | +``` yaml |
| 275 | +--- |
| 276 | +title: "My Document" |
| 277 | +editor: |
| 278 | + markdown: |
| 279 | + references: |
| 280 | + location: block |
| 281 | + links: true |
| 282 | +--- |
| 283 | +``` |
| 284 | + |
| 285 | +You can alternatively enable reference links using the {{< meta tool.name >}} `quarto.visualEditor.markdownReferenceLinks` option. |
| 286 | + |
| 287 | +### Known Limitations |
| 288 | + |
| 289 | +There are a handful of Pandoc markdown extensions not currently supported by visual editing. These are infrequently used extensions, so in all likelihood they won't affect documents you edit, but are still worth noting. |
| 290 | + |
| 291 | +| Extension(s) | Example | Behavior | |
| 292 | +|---------------------|-------------------|--------------------------------| |
| 293 | +| Inline footnotes | \^\[inline\] | Converted to numeric footnote. | |
| 294 | +| Footnote identifiers | \[\^longnote\] | Converted to numeric footnote. | |
| 295 | +| Example lists | (\@) First example | Read/written as ordinary numbered lists. | |
| 296 | +| Auto-list numbers | #\. First item | Read/written as ordinary numbered lists. | |
| 297 | +| Reference links | This is a \[link\] | Converted to ordinary links. | |
| 298 | +| MultiMarkdown attributes | \# Heading \[id\] | Converted to Pandoc attributes. | |
| 299 | + |
| 300 | +The visual editor is unable to parse non-YAML title blocks (e.g. old-style % titles or MultiMarkdown titles) and also unable to parse non top-level YAML metadata blocks. If these forms of metadata are encountered, visual mode will fail to load with a warning. |
| 301 | + |
| 302 | +Note that support for reference links can be enabled via the `editor: markdown: references: links` option in document or project YAML, or the {{< meta tool.name >}} `quarto.visualEditor.markdownReferenceLinks` option. Reference links will be written according the reference location option (either the `block` or `section` in which they appear, or alternatively at the end of the `document`). |
0 commit comments