Editing code
FreeThe code area is where your files live. It works with tabs and as many splits as you like, and it uses Monaco, the editor engine of VS Code. Files that aren't text open in matching viewers: images, PDFs, spreadsheets, Word documents, archives and more. Many of them you can edit right in the editor.
What you do here
- Tabs: open, close, restore and move files
- Splits: files side by side and stacked
- The code editor: shortcuts, view, ⌘-click jumps
- Encoding, line endings and language: pick UTF-8, ISO-8859-1, LF/CRLF and the language mode
- Snippets and Emmet: templates you tab through
- Preview: Markdown, JSON and SVG next to the code, HTML in the browser
- Viewers for files without text: which formats exist and how view and code work together
- Images: zoom, rotate, crop, convert
- PDF: read, search, edit pages, highlight, sign
- Spreadsheets: CSV and Excel: sort, filter, formulas, formats
- Word documents: edit, export as PDF, read older formats
- More formats: archives, certificates, fonts, mails, media, hex and very large text files
How the editor saves, detects conflicts and keeps earlier versions is in the Saving & history chapter.
Parts of the code area
| Part | What is there |
|---|---|
| Tab strip | one tab per file or view, on the right the Split right and Split down buttons |
| Editor group | the area below a tab strip; splitting creates several groups |
| Empty group | shows the most important shortcuts: ⌘P, ⇧⇧, ⌘K, ⇧⌘F, ⌥F12 and ⌘⎋ |
| Status bar | cursor, indentation, line endings, encoding and language of the active file (Status bar) |
Free and Premium
Everything in this chapter is free, including editing and saving images, PDFs, Excel and Word files. Opening files on a server is part of Remote and therefore of WebDonkey Premium.
Tabs Free
Every open file gets a tab. Tools, terminals, comparisons, the local history and the settings can live as tabs in the code area too. You open, close, move and bring back tabs the way you know from VS Code or PhpStorm.
How to do it
Opening a file
- click the file in the project tree, or select it and press ↩ or Space
- by name with ⌘P, from the recently used ones with ⌘E
- drag files from Finder onto the code area
- right-click in the project tree › Open to the side: opens the file in a new split on the right
If the file is already open, its tab comes to the front. The code area has no transient preview tabs that the next click replaces: a tab is open until you close it.
Closing a tab
- Click the × in the tab, press ⌘W or middle-click the tab.
- If the file has unsaved changes, the editor asks “Save changes to “Name”?” with Save, Don't save and Cancel.
Bringing a tab back
⇧⌘T (Reopen closed tab) brings back the tab you closed last, several times in a row, up to 30 tabs. The command skips terminal tabs: the shell ends with its tab, there is nothing to bring back.
What a tab shows
| Sign | Meaning |
|---|---|
| dot instead of × | unsaved changes; hovering turns it into the × |
| grey suffix after the name | two open files share a name, the suffix names the folder that tells them apart |
| coloured line on top | the active tab of the group you are working in; a red line marks files of a server connection marked as production |
| tooltip | the full path |
The tab strip scrolls by itself so the active tab is always fully visible.
Shortcuts
| Action | Shortcut |
|---|---|
| Close tab | ⌘W or middle-click |
| Reopen closed tab | ⇧⌘T |
| Next tab | ⇧⌘] |
| Previous tab | ⇧⌘[ |
| Recent files | ⌘E |
A tab's context menu
| Entry | What it does |
|---|---|
| Close (⌘W) | closes this tab |
| Close others | closes every other tab of this group, asking about unsaved ones |
| Close all | closes every tab of this group |
| Split right (⌘\) | splits the group to the right, the file then shows twice |
| Split down | splits the group downwards |
| Reveal in project | files only: selects the file in the project tree |
| Copy path | files only: copies the full path |
| Back to its side | tools only: docks the tool back at its place |
| Open in own window | tools that can do it: turns it into a window of its own |
Moving tabs
Drag a tab to another spot in the tab strip, into another group, or onto the edge of a group to create a new split. A line or an area shows where it lands.
See also
Splits Free
You can split the code area as often as you like, side by side and stacked, to see several files at once: a template next to its stylesheet, a test below the class, or the same file at two places.
How to do it
- Open the file you want to put next to another one.
- Press ⌘\ (Split editor right). The group splits and the active file is in both halves.
- Open another file in the new half, for example with ⌘P.
Other ways to split
- Split editor down: in the View menu, the command palette and a tab's context menu; no shortcut of its own
- the two buttons at the right of the tab strip: Split right and Split down
- drag a tab onto the left, right, top or bottom edge of a group: an area shows where the new half appears
- right-click in the project tree › Open to the side
- ⌥⌘-click a reference in the code: the target opens in the split next to it (The code editor)
Working with splits
- The active group is the one with the coloured line above its active tab. New files open there.
- The same file in two groups is one document: a change shows in both at once, but each group keeps its own scroll position.
- Tools and terminals exist only once. Splitting therefore only takes a file along, never a tool tab.
- You drag the divider between two groups with the mouse. Like the tool window edges, it snaps at ¼, ⅓, ½, ⅔ and ¾, and a double-click switches to ½.
Empty groups
When you close the last tab of a group, the group disappears, unless it is the last one. A group that was empty from the start, for example because you split while a tool or terminal was in front, stays until you close it.
An empty group shows the most important shortcuts:
| Command | Shortcut |
|---|---|
| Open file… | ⌘P |
| Search everywhere | ⇧⇧ |
| Command palette | ⌘K |
| Find in files | ⇧⌘F |
| Terminal | ⌥F12 |
| Claude | ⌘⎋ |
Close empty group (a button in the group and at the right of its tab strip) or ⌘W closes it. The last group always stays.
See also
The code editor Free
For editing text, the editor uses Monaco, the same engine as VS Code. You get multiple cursors, code folding, find and replace, syntax colouring for many languages and suggestions while you type. On top come ⌘-click jumps that understand templates, classes and snippet keys in PHP, Shopware, Symfony and Laravel projects.
Where to find it
Every text file you open lands in this editor. Its commands are in the Edit, View and Go menus and in the command palette.
Important shortcuts
| Action | Shortcut or way |
|---|---|
| Save / Save all | ⌘S / ⌥⌘S |
| Find in the file | ⌘F |
| Replace in file | ⌘R |
| Duplicate line or selection | ⌘D |
| Add next occurrence to selection | ⌥⌘G |
| Go to line… | Go menu or command palette |
| Format document | Edit menu or command palette |
| Copy reference (path:line) | ⇧⌥⌘R, copies something like src/app.ts:42 |
| Send selection to Claude | ⌥⌘K, see Selection to Claude |
| Compare with HEAD | Git menu or command palette |
| Toggle preview (Markdown/JSON) | ⇧⌘V, see Preview |
| Jump to the target of a reference | ⌘-click, in the split next to it with ⌥⌘-click |
Unlike VS Code, ⌘D duplicates a line, as in PhpStorm. You add the next occurrence to the selection with ⌥⌘G. Copy reference puts the path relative to the project and the cursor's line on the clipboard, in the form Claude and every terminal understand.
Renaming a tag in HTML or JSX renames its closing tag too.
Adjusting the view
In the command palette and the View menu: Toggle minimap, Toggle word wrap, Editor font: larger and Editor font: smaller (one point per step, from 9 to 28).
Everything else is in the settings:
| Area | What you set there |
|---|---|
| Settings › Editor, group Display | Line numbers (On, Relative to the cursor, Off), Minimap, Word wrap, Ruler at column (0 means no ruler), Show whitespace (In the selection out of the box), Colored bracket pairs, Sticky scroll, Markdown toolbar, Code folding, Cursor, Cursor blinking |
| Settings › Editor, group Indentation | Tab width (4), Spaces instead of tabs (on), Take indentation from the file (on) |
| Settings › Font, group Editor | Typeface, Font size (13), Line height, Letter spacing, Font weight, Ligatures |
An .editorconfig in the project always wins over your settings for indentation. More under Actions on save and Editor settings.
Jumping with ⌘-click
Hold ⌘ and hover a reference. The editor underlines it and the tooltip shows where it leads, such as "→ path" or "+ 2 more targets, ⌘-click to choose".
- ⌘-click opens the target. If there are several, the Go to list appears, each entry with its role: Definition, Original, Override, Alias, Types or Path match.
- ⌥⌘-click opens the target in the split next to it.
- If nothing is found, the tooltip says “No target found for “text””.
What the editor resolves:
| Reference | Example | Target |
|---|---|---|
| Twig templates with namespace | @Storefront/storefront/base.html.twig, sw_extends |
the original and every override in plugins, themes and apps, in inheritance order |
| PHP classes | Context, Foo::class, class names in services.xml or YAML |
the class's file, through use lines and Composer |
| JS and TS imports | aliases from tsconfig, Vite or webpack, Shopware's src/ alias, Node packages |
the imported file |
| Laravel and Blade | view('admin.users.index'), @include(…), <x-alert> |
the view or component |
| Snippet keys | 'checkout.addToCart'|trans, $tc('…') |
the line in every snippet file |
| Config keys | SwpX.config.foo |
the entry in config.xml |
| Paths | src/app.php:42 |
the file, at that line |
| Web links | https://… |
your default browser |
If no rule knows the reference, the editor offers files whose path ends the same way.
While you type, the editor also suggests Twig block names from the parent templates, snippet keys for |trans and $tc(…), and plugin settings for config('…').
⌘-click settings
Under Settings › Editor, group ⌘-click, all on out of the box:
| Setting | Meaning |
|---|---|
| ⌘-click jumps to declarations | switches the jumps on or off |
| Find unknown paths by their ending | the safety net for references no rule knows |
| Also search vendor/ | when nothing else matches, the editor indexes vendor/ once and searches it too |
| Suggest blocks, snippet keys and config keys | the suggestions while typing |
| Own aliases | one rule per line, such as @Foo => packages/foo/views; relative paths start at the project. Per project they live in .webdonkey-editor/aliases.json. |
What else happens in the gutter and the line
- Git in the gutter: coloured marks show changed, new and deleted lines since the last commit, a click shows the change. See Git in the gutter.
- Status bar: line and column, selection, indentation, line endings, encoding and language. See Encoding, line endings and language.
- AI in the code: explain, adjust and suggestions while typing. See AI actions and Suggestions while typing.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| ⌘-click doesn't find a template | it lives in a folder no rule knows | add a rule under Own aliases |
| The indentation changes after opening | an .editorconfig in the project sets it |
adjust the .editorconfig |
| Format document does nothing | there is no formatter for this language; Monaco formats JSON, CSS, HTML and JS/TS | run a formatter in the terminal |
See also
Encoding, line endings and language Free
On the right of the status bar are the line endings, the encoding and the language mode of the active file. All three are buttons: you reopen a file in another encoding, save it in another one, switch its line endings or tell the editor which language a file really is.
Where to find it
At the bottom right of the status bar as soon as a text file or a comparison is in front: for example LF, UTF-8 and PHP. They are hidden when Cursor, language and indentation under Settings › Features, group Status bar, is off.
How to do it
Reading a file in another encoding
The typical case: an old template file shows umlauts as garbled characters.
- Click the encoding in the status bar, such as UTF-8.
- Choose Reopen with encoding and then the right one, such as Windows-1252.
- The editor reads the file again. From now on it also saves it in that encoding.
With unsaved changes, Reopen with encoding is greyed out and says "save first": reading the file again would replace your changes.
Saving a file in another encoding
- Click the encoding.
- Choose Save with encoding and the target encoding, such as UTF-8.
- The editor saves right away in that encoding and keeps it for further saves.
Switching line endings
Click LF or CRLF (Switch line endings (LF/CRLF)). Every line of the file gets the other line ending. This is a normal change: the file counts as unsaved, ⌘Z takes it back, ⌘S or autosave writes it.
Choosing the language mode
When the editor takes a file for the wrong language, for example a .inc as PHP although it contains HTML:
- Click the language in the status bar (Select language mode).
- Type a few letters into the "Search language…" field, such as "html".
- Pick the language. Colouring and suggestions follow at once.
Auto detect at the top of the list goes back to the language the editor derives from the file name; the name of that language is shown next to it. Your choice holds while the file is open. Close all its tabs and the editor detects the language by itself the next time.
The encodings
| Entry | Meaning |
|---|---|
| UTF-8 | the standard for almost everything |
| UTF-8 with BOM | UTF-8 with an invisible mark at the start of the file; some Windows programs expect it. The mark is never part of the text, the encoding decides whether it is written. |
| Windows-1252 | the Western European Windows encoding, which also knows €, typographic quotes and dashes |
| ISO-8859-1 | Latin-1, common in older shops and templates |
The current encoding has a check mark in both submenus.
What happens in the background
- When opening, the editor checks whether the file is valid UTF-8 and remembers a BOM. If it isn't, it reads it as ISO-8859-1 so no characters get lost. It never detects Windows-1252 by itself; you pick that with Reopen with encoding.
- When saving, it writes in the encoding it read with. An ISO-8859-1 file stays ISO-8859-1.
- If you reopen as UTF-8 a file that isn't UTF-8, invalid bytes show as replacement characters. Save then and the original characters are gone. In that case use Reopen with encoding with the right encoding.
- Characters the encoding doesn't know: if a Windows-1252 or ISO-8859-1 file contains a character that encoding can't store, such as an emoji, the editor asks “Name” cannot stay ISO-8859-1 with Save as UTF-8 and Cancel.
- New, empty files get their line endings from the project's
.editorconfig(end_of_line), otherwise LF.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Umlauts show as two odd characters | the file is UTF-8 but was read differently, or the other way round | Reopen with encoding with the other encoding |
| Reopen with encoding is greyed out | there are unsaved changes | save or undo |
| After saving, Git shows every line as changed | the line endings or the encoding were switched | switch back in the status bar and save again |
| The status bar shows no encoding | no text is in front, or the entry is switched off | bring a text file to the front, check the setting |
See also
Snippets and Emmet Free
For the languages you edit most, the editor comes with templates: loops, classes, functions, Twig blocks and more. You type a prefix and then tab through the placeholders with ⇥. Emmet turns short expressions into whole HTML structures and CSS rules.
How to do it
- Type
foreachin a PHP file. - Snippets are at the top of the suggestion list, with a description and the full template. Confirm with ↩ or ⇥.
- The cursor is in the first placeholder. Type the name, ⇥ jumps to the next one, ⇧⇥ back. After the last placeholder the cursor sits in the body.
The prefixes
| Language | Prefixes |
|---|---|
| JavaScript, TypeScript | for, forof, forin, if, ife, fn, afn, af, try, switch, class, cl (console.log), imp (import), sto (setTimeout) |
| PHP | php, ns, class, construct, pubf, prof, prif, fn, foreach, foreachk, for, if, ife, try, match, dump, dd |
| HTML | html5, div, a, img, ul |
| Twig (plus the HTML prefixes) | if, for, block, sw_block, extends, sw_extends, include, set, trans |
| CSS, SCSS, Less | media, flex, grid |
| Markdown | code, table, link, img |
Emmet
Emmet writes nested structures from one line. Type div.card>h2+p*2 and press ⇥: you get a div with the class card, containing a heading and two paragraphs. In stylesheets, m10 becomes margin: 10px;.
| Languages | Emmet for |
|---|---|
| HTML, PHP, Twig, Handlebars, Razor | HTML structures |
| CSS, SCSS, Less | CSS rules |
Emmet is off in JavaScript and TypeScript, so not every identifier gets HTML suggestions.
Settings
Settings › Editor, group Typing: Emmet (on out of the box). Switched off, the snippets stay.
See also
Preview Free
You see Markdown, JSON and SVG files rendered next to the code while you type. HTML files open in the browser with one click. Markdown files also get a toolbar that formats without typing the syntax.
Where to find it
- ⇧⌘V (Toggle preview (Markdown/JSON)), in the View menu and the command palette
- the Preview button at the top right above the file
How to do it
- Open a Markdown, JSON or SVG file.
- Press ⇧⌘V or click Preview. The preview opens as a tab "Preview: name" in a new split on the right.
- Keep typing in the code. The preview follows every change, even before you save.
- ⇧⌘V again closes the preview.
Rename the file and the preview moves along.
What the preview shows
| File type | Preview |
|---|---|
Markdown (.md, .markdown, .mdx) |
the rendered page with tables, task lists, callouts, highlights and [[wikilinks]]; code blocks are coloured as in the editor |
JSON (.json, .jsonc, .json5, not .lock) |
a collapsible tree; if the JSON is invalid, it says "Not valid JSON" with the position of the error |
| SVG | the image with Zoom out, Zoom in and Fit; if it can't be drawn, it says "The SVG can't be rendered right now" |
In the Markdown preview you can click:
- A task list checkbox ticks the task in the text. That is a normal change, ⌘Z takes it back.
- A
[[wikilink]]opens the file it names. - A web link opens in your default browser.
The preview doesn't render HTML inside Markdown. It shows an SVG as an image: scripts in it don't run, and nothing is loaded from the network.
The Markdown toolbar
Every Markdown file has a toolbar with these functions:
| Group | Buttons |
|---|---|
| Text | Bold (⌘B), Italic (⌘I), Strikethrough, Inline code |
| Paragraph | Heading opens a choice: Normal text, Heading 1 to Heading 6 |
| Lists | Bulleted list, Numbered list, Checkbox, Quote |
| Blocks | Code block opens a choice of languages, plus No language and, inside a block, Remove code block; Horizontal rule |
| Insert | Link and Image (ask for the address), Insert table (asks for Columns × rows) |
| Only with the cursor in a table | Insert row above, Insert row below, Insert column left, Insert column right, Delete row, Delete column, Align column left, Center column, Align column right, Align table |
In a narrow window, further buttons are under More. Every function is also a command in the palette while the cursor is in a Markdown file.
Hide the toolbar with Toggle Markdown toolbar (View menu) or under Settings › Editor, group Display: Markdown toolbar.
The editor shows notes from your brain in a view of their own, with live preview and everything Obsidian can do. See Notes.
HTML in the browser
For HTML files (.html, .htm, .xhtml, .svg) there is Open in browser: in the File menu, the command palette and the file's context menu in the project tree. The file opens in your default browser straight from disk. For a site from WebDonkey, Open in browser in the status bar is the better choice, it opens the site's address.
See also
Viewers for files without text Free
Files that aren't text open in a matching viewer instead of the "Binary file" notice: images, PDFs, spreadsheets, Word documents, archives, certificates, fonts, mails, audio and video. You can also edit and save images, PDFs, Excel and Word files there.
Where to find it
Open the file like any other, for example with a click in the project tree or with ⌘P. The editor picks the viewer by itself, from the extension and the file's first bytes. That way a JPEG named .png still lands in the image viewer, and a file without an extension finds its viewer.
Which viewer for which format
| Formats | Viewer | Editing |
|---|---|---|
| PNG, JPEG, GIF, WebP, AVIF, HEIC, TIFF, BMP, ICO | Images | yes |
| yes | ||
| CSV, TSV | Spreadsheets | yes |
Excel (.xlsx, .xlsm), OpenDocument (.ods) |
Spreadsheets | yes, .ods view only |
Word (.docx, .docm, .dotx) |
Word documents | yes |
.doc, .rtf, .odt |
Word documents | read, save as .docx |
archives, certificates, fonts, emails, audio and video, SQLite, Keynote, Pages, Numbers, PowerPoint, .xls |
More formats | no |
| every other binary file | hex view (More formats) | no |
| text files over 20 MB | large text files (More formats) | no |
SVG is text: it opens as code, and you see the image in the preview.
View and code
Some formats are text and still have a viewer, such as CSV, certificates (.pem), emails (.eml) or RTF. They open as code, with a View button at the top right that shows the same file in its viewer. If the code has unsaved changes, the editor saves first.
In the viewer, the Code button in the bar above takes you back. It is greyed out while the viewer has unsaved changes ("Save your changes first").
Empty Word, PDF and Excel files open straight in the viewer, as an empty document. That way you fill a file you just created with Empty file right in the matching format. New Word and Excel files are easiest to create with New › Documents in the project tree (New file).
Saving in a viewer
- ⌘S saves just like for text. The dot in the tab shows unsaved changes, and the editor asks when you close or quit.
- Autosave never writes into a viewer. You always save changes to images and documents yourself.
- The editor writes the file in one step, first checks whether it changed on disk in the meantime, and puts the previous version into the local history.
- New files, such as a PDF export, a converted image or a copy, are always created through a save dialog. Afterwards the editor reports "Saved name".
- If a format can't be written back, the editor says "This format can't be written back. Use "Save as copy" instead."
If the file changes on disk while the viewer is open, a viewer without changes quietly reloads it. With changes, the same bar as for text appears, with Reload (discard mine) and Keep mine (Conflicts with the disk).
Files from a server open in the viewer as a downloaded working copy. ⌘S uploads them straight back there, with the same check whether the file is newer on the server by now. See Remote files.
View only
When a file opens for viewing only, the bar above the viewer names the reason, such as "The file is read-only, so it opens for viewing only." Other reasons depend on the format: macros in Excel, text boxes in Word, encrypted PDFs. The format pages explain them. Where possible, the viewer offers Edit as copy: you then work on a copy and the original stays unchanged.
Settings
| Setting | Where | Default |
|---|---|---|
| Open files without text in a viewer | Settings › Features, group More features; off: no viewer is loaded, the editor shows "Binary file" | on |
| Keep binary files in the local history up to | Settings › Files & formats, group Local history; 0 turns it off, at most 200 MB | 50 MB |
| Pixel grid when zoomed in | Settings › Files & formats, group Images | on |
| Default quality for JPEG and HEIC | Settings › Files & formats, group Images | 82 % |
Free and Premium
All viewers are free, including editing and saving images, PDFs, Excel and Word files. Only files on a server need WebDonkey Premium, because Remote is part of it.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "Binary file" instead of a viewer | Open files without text in a viewer is off | switch it on |
| "Couldn't open this file" | the file is damaged or has another format than its extension says | open it with the program that created it |
| The Code button is greyed out | the viewer has unsaved changes | ⌘S, then Code |
See also
Images Free
Images open in the image viewer. You zoom down to the single pixel, rotate, flip, crop, resize, compress and convert to another format. Every edit can be undone, and nothing is saved until ⌘S.
Where to find it
Open an image in the project tree or with ⌘P. The viewer shows PNG, APNG, JPEG, GIF, WebP, AVIF, HEIC and HEIF, TIFF, BMP, ICO and CUR. SVG opens as code with a preview.
How to do it
Making an image smaller and saving it
- Open the image. The footer shows its size in pixels, file size and format.
- Click Resize. Enter a new Width or Height; with Keep aspect ratio the other value follows. The 25 %, 50 % and 200 % buttons work out the size for you.
- Click Apply. The footer says "1 edit, not saved".
- Press ⌘S. The image is saved in its own format.
Converting an image to another format
- Click Convert.
- Under Format, pick PNG, JPEG, HEIC, TIFF, GIF, BMP or AVIF. For JPEG, HEIC and AVIF you set the Quality.
- Click Save as copy… and choose place and name. The original stays unchanged.
The toolbar
| Button | What it does |
|---|---|
| Zoom out, Zoom in | zooms in fixed steps from 5 % to 6400 % |
| Percentage (Actual size (1)) | jumps to 100 % |
| Fit | fits the image into the area, but never enlarges it beyond 100 % |
| Rotate left, Rotate right | rotates by 90 degrees |
| Flip horizontally, Flip vertically | mirrors the image |
| Crop | drag a frame with the mouse, its size shows next to it; Crop applies it, Cancel or Esc discards it |
| Resize | new width and height, see above |
| Compress | for JPEG, HEIC and AVIF: a Quality slider, below it the old and the estimated new file size; Apply applies it. For lossless formats it says the file only gets smaller as JPEG or HEIC, with a Convert button. |
| Convert | saves a copy in another format, see above |
| Undo (⌘Z), Redo (⇧⌘Z) | steps through your edits |
| Pause animation, Play animation | animated images only |
| Compare with git HEAD | only when the image is in a Git repository and committed: shows HEAD and Now on top of each other, you move the dividing line with the mouse |
| Info | shows the properties on the right |
Without the mouse: + and - zoom, 0 fits, 1 shows 100 %. You also zoom with ⌘ and the scroll wheel or with two fingers on the trackpad. Esc ends cropping and closes open panels.
The commands Image: Rotate right, Image: Rotate left, Image: Flip horizontally, Image: Flip vertically, Image: Fit, Image: Actual size, Image: Undo edit and Image: Redo edit are in the command palette too. They act on the image in the active group.
Info
Info shows Size, Megapixels, File size, whether the image is Animated, and everything stored in the file: Colour space, Colour profile, DPI (horizontal) and DPI (vertical), Transparency, Bits per channel, Channels, Camera make, Camera model, Taken, Software, Artist, Copyright and Description.
Pixel grid
From 300 % the viewer shows pixels sharp instead of smoothed. From 800 % it adds a fine grid so you see every single pixel. You switch the grid off under Settings › Files & formats, group Images, with Pixel grid when zoomed in.
What happens in the background
- Edits run through macOS's image tool. Each step creates a working file of its own, so Undo is just one step back in that list.
- Only ⌘S writes the file. A JPEG, HEIC or AVIF is re-encoded exactly once, at 92 % quality, not at every step.
- Compress and Convert start with the quality from Default quality for JPEG and HEIC (82 % out of the box).
- The editor puts the previous version into the local history, up to the size you set.
Limits
- WebP and ICO can be read but not written. After an edit it says "This format can only be read. Save your edits with Convert as a copy."
- Animated images (GIF, APNG, animated WebP) open for viewing only: editing would keep a single frame.
- If the file is read-only, the editing tools are missing; Convert still works.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The editing buttons are missing | the image is animated, read-only or couldn't be read | use Convert as a copy |
| "That didn't work: …" | macOS couldn't run the step | try another step or format |
| Compare with git HEAD is missing | the image isn't committed or not in a repository | commit it first |
See also
PDF Free
PDFs open in the PDF viewer. You page through thumbnails and the outline, search the text, print and fill in forms. You can edit them too: rotate, delete, reorder and append pages from another PDF, highlight text in colour, add notes and place a signature as an image.
Where to find it
Open a .pdf file in the project tree or with ⌘P. An empty file with the .pdf extension opens as a document with one blank page. Edit it and save, and it becomes a real PDF.
How to do it
Appending pages from another PDF
- Click Append pages from another PDF and pick the PDF.
- The Append PDF dialog asks: "Which pages? Empty = all, or e.g. 1-3, 5". Leave the field empty for all pages.
- Click Append. The pages are added at the end of the document.
- Press ⌘S to save.
Saving pages as a new PDF
- Select the pages that should go into the new file in the sidebar (see below).
- Click Save pages as a new PDF. The Split off pages dialog suggests the selected pages, all of them without a selection. Adjust the range if needed, such as
2-4. - Click Save as… and choose place and name. The original stays unchanged, the message "Saved: path" confirms the new file.
Signing
- Click Place a signature.
- Draw with the mouse or trackpad, or click Pick image… for a PNG or JPEG. Clear starts over.
- Click Use and then the spot in the document (Esc cancels).
- Save with ⌘S.
The signature goes into the PDF as a picture, not as a digital signature.
The toolbar
| Button | What it does |
|---|---|
| Sidebar | shows or hides the sidebar |
| Page number | shows the current page; type a number and press ↩ to jump there |
| Zoom out, Zoom in | zooms, from 10 % to 500 % |
| Width, Page | fits the page width or the whole page |
| Search in document (⌘F) | opens the search |
| opens the macOS print dialog | |
| Undo, Redo | steps through the last 15 edits |
| Rotate page left, Rotate page right | rotates the selected pages or the current one |
| Delete page | deletes the selected pages or the current one; a PDF always keeps at least one page |
| Highlight selected text | marks the selected text; Highlight color: yellow, green, blue or pink |
| Add a note | click the spot, then enter the text and Add |
| Place a signature | see above |
| Append pages from another PDF | see above |
| Save pages as a new PDF | see above |
If the file can't be edited, the buttons from Undo on are missing. Instead it says View only with the reason (see below).
The sidebar
| Tab | Content |
|---|---|
| Pages | thumbnails of every page. A click selects a page and jumps there, ⇧-click selects a range, ⌘-click adds single pages. Dragging reorders the selected pages. |
| Outline | the PDF's bookmarks, a click jumps there; without any it says "This document has no outline." |
| Form fields | only for PDFs with a form: text fields, checkboxes and choice lists to fill in |
Searching
⌘F opens the "Search text" field. ↩ or ⌘G jumps to the next match, ⇧↩ or ⇧⌘G to the previous one. Next to it you see which match is highlighted. Esc closes the search.
Shortcuts
| Shortcut | Action |
|---|---|
| ⌘F | open the search |
| ⌘G, ⇧⌘G | next, previous match |
| ⌘+, ⌘- | zoom in, zoom out |
| ⌘0 | fit to width |
| ⌘Z, ⇧⌘Z | undo, redo |
| Esc | cancel a note or signature, close the search |
View only
So nothing gets broken, some PDFs open for viewing only. The bar shows View only and a reason:
| Reason | Meaning |
|---|---|
| locked | editing is locked for this file, for example because it is read-only |
| encrypted | encrypted PDFs are shown only, saving would damage them |
| damaged | the file is shown as far as possible but never overwritten |
| too large | the file is too large to edit and is streamed for viewing |
If a PDF is password protected, the viewer asks: "This PDF is password protected". With the password you can view it. A protected file is never edited.
What happens in the background
Every edit first changes the PDF in memory only. ⌘S writes it, and the previous version goes into the local history. New files from Split off pages are only created through the save dialog.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "This PDF cannot be opened." | the file isn't a valid PDF | check it with the program that created it |
| "Pages like 1-3, 5 (document has … pages)." | the page range doesn't fit | correct the range |
| "This image cannot be placed (PNG or JPEG)." | the signature is in another format | save it as PNG or JPEG |
| Delete page is greyed out | the document has only one page left | nothing to do |
| "View only: fields cannot be changed." | the PDF is open for viewing only | see "View only" |
See also
Spreadsheets: CSV and Excel Free
You see CSV and TSV files as a table with coloured columns or as text. Excel workbooks open with all their sheets, formulas, formats and borders. In both you sort and filter without changing the file until you want to, and edit cells as in a spreadsheet app.
Where to find it
- CSV, TSV (
.csv,.tsv,.tab) are text and open as code. Click View at the top right to see them as a table. - Excel (
.xlsx,.xlsm) and OpenDocument (.ods) open straight in the table view. An empty.xlsxfile opens as an empty workbook.
Working in cells
This applies to CSV and Excel alike:
| Key | What happens |
|---|---|
| arrow keys | move the selection; with ⇧ extend it, with ⌘ jump to the edge |
| ⇥, ⇧⇥ | one cell right or left |
| Page Up, Page Down, Home | page, go to the start of the row; ⌘Home to the first cell |
| ↩ or F2 | edit the cell; just start typing to replace its content |
| ↩ while editing | apply and move one cell down, ⇧↩ up, ⇥ right |
| ⌥↩ while editing | line break inside the cell |
| Esc while editing | discards the input |
| ⌘A | select all |
| ⌘C, ⌘V | copy and paste, also between the editor and other apps |
| ⌘Z, ⇧⌘Z | undo, redo |
Right-clicking cells offers Sort ascending, Sort descending, Insert row above, Insert row below, Delete rows, Insert column left, Insert column right and Delete columns.
Sorting and filtering
Sorting and filtering change only the view at first, not the file.
- Select a cell in the column you want to sort by.
- Click Sort ascending or Sort descending. Or click Filter and type into "Show rows containing …".
- A bar says "View: 12 of 230 rows, the file is unchanged".
- After sorting, Apply order writes the sorted order into the table. It is saved like any change with ⌘S. Show all in file order removes sorting and filter again.
Inserting rows works again once you show everything in file order. In Excel the editor doesn't sort rows with formulas or merged cells, so no references shift; it tells you what you can do instead.
CSV and TSV
The bar above the table:
| Element | What it does |
|---|---|
| Table, Text | switches between the table and the raw text with coloured columns |
| Delimiter | comma, semicolon, tab or vertical bar; the editor detects it on opening |
| Encoding | UTF-8, Windows-1252, Mac Roman (MACINTOSH), UTF-16LE and UTF-16BE, with BOM when the file has one; detected on opening, switchable only without unsaved changes |
| First row is header | keeps the first row at the top while scrolling and takes it out of sorting and filtering; the editor ticks it by itself when the row looks like a header |
| Sort ascending, Sort descending, Filter | see above |
| Undo | takes back the last step |
| right side | the selection and the number of rows and columns |
When saving, the editor rewrites only the rows you changed. All others keep their exact bytes, including quotes and line endings. If a cell contains a character the chosen encoding can't store, the editor names it and suggests removing it or saving a copy as UTF-8.
Excel
The toolbar
| Group | Buttons |
|---|---|
| History | Undo, Redo |
| Font | Font size, Bold, Italic, Underline, Strikethrough, Font colour, Fill colour, Remove colour (No fill, Automatic font colour) |
| Borders | Borders: All borders, Outside borders, Thick outside borders, Bottom border, Top border, Left border, Right border, No border |
| Alignment | Align left, Centre, Align right, Wrap text |
| Numbers | Number format: General, Number, Whole number, Euro, Dollar, Percent, Percent with decimals, Date, Time, Date and time, Scientific, Text, Custom format … (a format code as in Excel) |
| Cells | Merge cells, Unmerge cells, Freeze panes: Freeze top row, Freeze first column, Freeze above and left of cell, Unfreeze panes |
| Data | Sort ascending, Sort descending, Filter, Find and replace |
| Output | Export: Export sheet as CSV …, Export sheet as PDF … |
When merging, as in Excel, only the value of the top-left cell stays.
Formula bar and sheets
- On the left is the Cell address of the selection, next to it the Cell content with the formula. Type a formula starting with
=and the editor calculates it. If it is invalid, it says "This formula is not valid: …". - Results of functions the editor doesn't know yet are shown as they are in the file, marked from file. Excel and Numbers recalculate them when they open the file.
- The sheets are tabs at the bottom. + adds a New sheet. Double-click or right-click › Rename sheet renames, Move left and Move right reorder.
- Find and replace opens a field with Find, Replace with, Replace and Replace all, and shows the number of hits.
- Dragging the small square at the bottom right of the selection fills neighbouring cells.
What is kept when saving
The editor writes back only what you changed. What it can't edit stays unchanged in the file, and a bar names it: "Kept unchanged when saving: charts, pivot tables, pictures and shapes, macros, links to other workbooks, data tables". Macros never run in the editor.
View only and copy
Some workbooks open for viewing only, so nothing gets lost. The bar above names the reason:
- "it contains macros"
- "it uses Strict Open XML"
- "OpenDocument files cannot be saved here yet"
- "This file is read-only."
The buttons are there too:
- Open in Numbers/Excel opens the file in the app macOS uses for it.
- Edit as copy unlocks editing. The original stays as it is.
- Save copy … writes your version as a new file.
.ods files and read-only files can only be viewed, without a copy. Single sheets or cells can be locked: protected sheets, array formulas, chart and macro sheets. The editor then tells you why.
Free and Premium
Viewing, editing, saving and exporting CSV and Excel files are free.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The CSV shows everything in one column | the delimiter was detected wrongly | change the Delimiter |
| Umlauts are broken | the encoding doesn't match | change the Encoding, save or undo first |
| "Show all in file order first: …" | the view is sorted or filtered | Show all in file order |
| "The rows contain formulas. …" | sorting would move references | sort in Excel or Numbers |
| "This sheet is protected. …" | the sheet has sheet protection | unprotect it in Excel or Numbers |
See also
Word documents Free
Word files open as a page at their real size, with styles, fonts, lists, tables, pictures, headers and footers, comments and tracked changes. You edit them right in the editor and save back into the .docx with ⌘S. Older formats such as .doc, .rtf and .odt the editor reads, and saves them as .docx if you like.
Where to find it
Open a .docx, .docm or .dotx file in the project tree or with ⌘P. An empty file with one of these extensions opens as a new, empty document.
How to do it
- Open the document and click into the text.
- Edit it as in a word processor. ⌘B, ⌘I and ⌘U format, ⌘↩ inserts a page break.
- For the header or footer, click into the area above or below the text.
- Save with ⌘S. The editor writes back only what you changed.
The toolbar
| Group | Buttons |
|---|---|
| History | Undo, Redo |
| Text | Style (Normal, Heading 1 and every style of the document), Font, Font size, Bold (⌘B), Italic (⌘I), Underline (⌘U), Strikethrough, Superscript, Subscript, Font colour, Highlight (with No highlight) |
| Paragraph | Align left, Center, Align right, Justify, Bullets, Numbering, Decrease indent, Increase indent, Paragraph … |
| Insert | Table, Insert picture, Link, Page break (⌘↩), Insert page number |
| Document | Find and replace (⌘F), Page setup …, Comments, and for documents with tracked changes Accept all changes and Reject all changes |
| Output | Print, Export as PDF, New document |
The dialogs
| Dialog | Fields |
|---|---|
| Paragraph … | Indent (cm): Left, Right, First line (negative = hanging); Spacing (pt): Before, After; Line spacing: Single, 1.5 lines, Double, As in the document |
| Page setup … | Paper size, Orientation (Portrait, Landscape), Margins (cm): Top, Bottom, Left, Right |
| Table | Insert table with Rows and Columns; inside a table Row above, Row below, Column left, Column right, Delete row, Delete column, Delete table, Merge cells, Split cell, All borders, No borders, Shading |
| Link | "Link address (empty = remove link)" |
| Find and replace | Find, Replace with, Match case, Replace, Replace all, a counter such as "1 of 3" |
At the bottom of the window
The footer shows words, characters, the paper size in centimetres and the Zoom (50 % to 200 %). Comments shows the document's comments on the right.
Links in the text open in the browser with ⌘-click while editing, with a plain click in a read-only document.
View only
If a document contains something the editor can't write back safely, it opens with the note View only. It names what it is: text boxes, SmartArt, shapes in the text, sections with columns, fields, macros (never run), positioned frames, embedded foreign content, subdocuments, editing protection, an unknown encoding or an unknown format. You then have two buttons:
- Open in Word/Pages opens the file in the app macOS uses for it. If that fails, Finder shows the file.
- Edit a copy asks for a name (suggested: "Name (copy).docx"), creates the copy and opens it. In the copy you edit everything the editor can show. What it can't show is kept unchanged, and a line above the document says so.
Single parts that can't be edited, such as equations, embedded objects or content controls, show as placeholders with their name. They stay as they are when saving. If the file is read-only, the document shows Read-only.
Older formats
macOS converts .doc, .rtf and .odt for display. They open with Read only. Save as docx converts the file and saves it through a save dialog as a new .docx, which you then edit normally. The original stays unchanged. RTF is text and opens as code first; View switches to this view.
Exporting and new documents
- Export as PDF writes the document, as you see it, into a new PDF file.
- New document creates an empty
.docx(suggested: "Document.docx") and opens it. - You can also create new Word files with New › Documents in the project tree (New file).
Free and Premium
Viewing, editing, saving and exporting Word documents are free.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "This file can't be read." | it is damaged, encrypted or not a Word document | open it in Word or Pages |
| View only. with a list | the document contains something that would get lost when saving | Edit a copy or Open in Word/Pages |
| "macOS could not convert this document." | an older format couldn't be read | open it in Word or Pages |
See also
More formats Free
Besides images, PDFs, spreadsheets and Word documents, the editor shows many more formats in viewers of their own: archives, certificates, fonts, emails, audio and video, SQLite files and office formats from Apple and Microsoft. Unknown binary files open in a hex view, very large text files page by page. All these viewers only display, they don't change the file.
Where to find it
Open the file like any other. The editor recognises the right viewer by extension and content (Viewers for files without text). Certificates in text form and .eml files open as code first; View at the top right switches to the viewer.
The formats
| Format | Extensions | What the viewer shows |
|---|---|---|
| Archives | .zip, .tar, .gz, .tgz, .7z |
the entries as a tree with sizes, above it "N entries, size unpacked" |
| Certificates | .pem, .crt, .cer, .csr |
every certificate and request in the file with Subject, Issuer, Valid, Alternative names, Serial, Signature and Chain |
| Fonts | .ttf, .otf, .woff2 |
name and style, plus a sample in five sizes |
| Emails | .eml |
From, To, Cc, Date, subject, the body and the Attachments |
| Audio and video | .mp3, .m4a, .wav, .mp4, .mov, .webm |
a player with Duration and file size |
| SQLite | .db, .sqlite, .sqlite3 |
size, number and size of pages and the database's text encoding |
| Apple and Microsoft office | .key, .pages, .numbers, .pptx, .ppt, .xls |
a Quick Look preview of the first page |
| anything else | any | hex view |
| large text files | over 20 MB | page-by-page view with a filter |
Archives
Clicking a folder expands it. Save copy next to an entry unpacks exactly that file through a save dialog; the message "saved to path" confirms it. The editor never just unpacks into a folder.
- Entries whose path would lead out of the target folder are marked unsafe path and are not extracted.
- The list shows at most 10 000 entries or 500 MB unpacked size. For larger archives a notice says only the first part is listed.
.7zarchives need the7zzprogram. If it isn't installed, the editor says so.
Certificates
- Valid shows the period and, after it, how long the certificate is still valid ("(324 days left)"), when it expires ("(expires in 12 days)") or how long ago it expired.
- Each certificate is labelled Certificate or Certificate request, plus CA and self-signed where that applies.
- Chain says whether the next certificate in the same file issued this one.
- A private key in the file only shows as the note "Private key. Shown masked, the content stays hidden."
Emails
The viewer shows a mail's HTML part shielded: scripts don't run and nothing is loaded from the network. Without a subject it says "(no subject)". Every attachment has Save, which stores it through a save dialog.
SQLite
The viewer shows only the header facts. The Database window can't open plain SQLite files yet, and the viewer says so. If the file doesn't start like a SQLite database, a notice says that.
Quick Look
Keynote, Pages, Numbers, PowerPoint and older Excel files (.xls) are shown through macOS Quick Look: "Quick Look preview of the first page. View only." To edit them, open them in the matching app.
Hex view
Every binary file without another viewer opens in the hex view: the offset on the left, the bytes in the middle, the characters on the right. The editor only loads what you see, so even large files open instantly.
- Click into the Jump to offset field ("Offset, e.g. 0x1F40").
- Type the offset in hex with
0xin front, withhafter it (1f40h) or as a decimal number. - Click Go or press ↩.
Large text files
Text files over 20 MB, such as logs, open read-only in sections of 256 KB:
| Element | What it does |
|---|---|
| Previous, Next | load the previous or next section |
| Start, End | jump to the start or end of the file |
| Follow | checks every second whether the file grew and shows the end, like tail -f |
| "Show lines containing …" and Filter | searches the whole file, ignoring upper and lower case, and lists the hits with their position in the file |
| Clear filter | back to the normal view |
The hit list shows at most 2000 lines, with "list cut off" above it beyond that. Clicking a hit (Show in the file) jumps to that spot in the file.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "7z archives need 7zz, which is not installed." | the program is missing | install 7zz, for example with Homebrew |
| "The file is larger than 500 MB unpacked and is not opened." | the entry is too big for the editor | unpack it with an archive app |
| "No certificate or request found in this file." | the file contains something else | check the file |
| "This file cannot be played here." | the format or codec isn't supported | open it in QuickTime Player |
| "Quick Look has no preview for this file." | macOS can't show this file | open it in the matching app |
| "The helper program took too long and was stopped." | converting or previewing took too long | open the file in the matching app |