Markdown mode

The Markdown editor shows you the file as it is: frontmatter aside, exactly the text Hugo will read. It’s built on CodeMirror 6, so you get syntax highlighting, search, folding, multiple cursors and, if you want it, Vim. You’ll want it for anything the visual editor can’t express cleanly, raw HTML mostly, and for the days when you’d rather just type.

Switching modes#

The Markdown button at the far right of the visual editor’s toolbar brings you here; the Visual button at the far right of this one takes you back. Emet remembers your choice. The editor.default_mode setting in cms.yaml only decides which mode you see before you’ve made that choice; see Visual mode.

The toolbar#

The Markdown editor’s toolbar is a thin strip with everything pushed to the right:

• A mode badge (NORMAL, INSERT, VISUAL, VISUAL LINE, VISUAL BLOCK or REPLACE) when Vim mode is on.
• Vim toggles Vim keybindings.
• Line # toggles line numbers, which are off by default.
• Focus toggles focus mode, which hides everything except the editor and centres the text in a narrower column.
• Visual switches back to the visual editor.

The Vim and Line # settings are remembered across sessions.

Editing#

Markdown syntax is highlighted (headings bold, emphasis italic, links and code coloured) in a light or dark palette that follows Emet’s theme. The line your cursor is on is tinted, brackets and quotes auto-close and matching pairs light up, and long lines wrap rather than scroll sideways. Tab and Shift+Tab indent and unindent, and the usual CodeMirror editing commands are all there, from Alt+Up to move a line to Ctrl+Alt+Down to add a cursor. The shortcuts page has the list.

Formatting keys#

Ctrl+B wraps the selection in **. Ctrl+K asks for a URL and turns the selection into [selection](url), or inserts [link text](url) with the placeholder selected if nothing was selected.

Ctrl+I wraps the selection in *.

Search#

Ctrl+F opens CodeMirror’s search panel at the bottom of the editor. It has find and replace fields, with options for case sensitivity, regular expressions and whole-word matching, and matches are highlighted in yellow as you type. Ctrl+G and Ctrl+Shift+G step forwards and back, and Esc closes the panel. There’s no separate replace shortcut, because replace lives inside the same panel.

Folding#

The gutter shows fold markers next to headings, code blocks and other foldable regions. Click a marker to collapse the region, or use Ctrl+Shift+[ and Ctrl+Shift+] (Cmd+Alt+[ and Cmd+Alt+] on a Mac).

Shortcodes#

Hugo shortcodes get a blue background and outline so they stand out from the prose, in both the {{< >}} and {{% %}} forms, including .inline shortcodes and closing tags. There are no editing cards here; a shortcode is just text, which is rather the point.

The highlighter is a regular expression rather than a parser, and it only understands parameters that are bare words or key="value" pairs. A shortcode with a quoted positional argument, like {{< ref "posts/hello" >}}, or with a hyphen in its name, isn’t highlighted at all. It still works in Hugo; it just doesn’t get the blue box.

Ref and relref autocomplete#

Start typing a ref or relref shortcode, as in {{< ref "blo >}}, and once you’re inside the quotes Emet offers content paths from your sections as completions, in the form Hugo’s ref wants (no content/ prefix, so blog/my-post.md). Keep typing to filter the list. The suggestions come from the entry lists Emet has already loaded, so a section you haven’t opened this session won’t be in there yet.

Review comments#

If the entry is part of an open pull request with review comments on it (see Publication), the commented lines get an amber marker in the gutter with the number of threads, and unresolved ones get a soft highlight across the line. Click a marker to open the Comments tab in the right panel. The gutter takes up no space when there’s nothing to show.

Vim mode#

Click Vim and the editor switches to Vim keybindings, courtesy of @replit/codemirror-vim. The toolbar badge tells you which mode you’re in, colour-coded: amber for normal, green for insert, violet for the visual modes and rose for replace.

Two mappings are added on top of the defaults:

Ctrl+V enters visual block mode, with Ctrl+Q as a fallback for browsers that grab Ctrl+V for paste. Once you have a block selected, d, c, I, A, y, p, r, > and < do what you’d expect across the selected lines. Note that these use Ctrl on every platform, including macOS.

The usual motions, operators and text objects are all there. Vim mode is remembered across sessions, so you only have to switch it on once.

Where next?#

• Keyboard shortcuts for the complete list of bindings in this mode.
• Visual mode for the other editor.