# Objective

- Fixes #33819
- The `preview_tabs` documentation says preview tabs "close
automatically when you switch to another file unless you explicitly pin
them". They do not close. Moving to another file leaves the preview tab
open — either still as the preview tab, or converted into a regular one.
Four people ran into this on the issue over the past year.
- The same section then lists the ways to turn a preview tab into a
regular tab, and two of them are missing, including the pinning that the
sentence above uses as its counter-example.

## Solution

Two corrections to the `Preview tabs` section of
`docs/src/reference/all-settings.md`. No behaviour was touched.

**The description.** A pane holds a single `preview_item_id`, so there
is at most one preview tab at a time. What happens to it when you move
to another file depends on the path:

- Opening a not-yet-open file in preview mode from the project panel or
file finder goes through `Pane::open_item`, which calls
`close_current_preview_item` — that really does close the old tab
(`remove_item`) and hands back its index, and the new file is inserted
there.
- Code navigation with the default
`enable_keep_preview_on_code_navigation: false` instead calls
`unpreview_item_if_preview` on the old item *before*
`replace_preview_item_id`, so the previous file stays open as a regular
tab.

A third path, the file finder with the default
`enable_preview_from_file_finder: false`, opens the new file as a
regular tab and leaves the existing preview tab alone entirely.

Rather than spell out every path in a settings description — the
`enable_preview_*` settings immediately below already cover them — the
new wording sticks to what holds in all of them: a pane keeps at most
one preview tab and opening another file in preview mode takes over that
slot, and switching to a file that is already open does not close the
preview tab. That second half is the case the issue actually reports.

**The list.** Two more ways to convert a preview tab into a regular tab:

- Pinning it — `change_tab_pin_state` calls `unpreview_item_if_preview`
on the `Pin` branch.
- `pane::TogglePreviewTab` — the action dedicated to exactly this,
registered whenever preview tabs are enabled.

## Testing

- Built a debug Zed and walked through the steps from the issue on a
scratch project of `a.txt` / `b.txt` / `c.txt`: with `a.txt` open as a
regular tab and `b.txt` opened as a preview tab, clicking back to
`a.txt` leaves the `b.txt` preview tab open, which is what the current
wording says should not happen. Single-clicking `c.txt` takes over the
same slot rather than adding a second preview tab, and pinning the
preview tab drops the italics.
- Ran the docs steps from `run_tests.yml` locally: `zed
--dump-all-actions > crates/docs_preprocessor/actions.json`, then
`mdbook build ./docs` on mdbook 0.4.37 to match CI. Exit 0 with no
preprocessor errors, and both new `{#action ...}` references resolve —
the rendered page reads "pane: toggle pin tab" and "pane: toggle preview
tab" in the same style as the existing "project panel: open permanent".
- `cargo test -p workspace --lib` — 272 passed, 0 failed, including
`test_close_other_items_unpreviews_active_item`,
`test_reopening_closed_item_after_unpreview`, and the proptest that
opens random paths with random `allow_preview` and asserts a pane never
holds more than one preview item.

## Notes for review

- Several people on the issue would rather the *behaviour* changed, so
that preview tabs close on any tab switch the way the docs currently
describe. I left that alone deliberately: the issue is typed `Docs`, so
this PR only makes the prose match the implementation. Happy to open a
discussion separately if it is worth pursuing.
- Saving a file also unpreviews it (`Pane::save_item`), but I left it
off the list as redundant — you have to edit a file before you can save
it, and editing is already there. Say the word if you would rather it
were explicit.
- The comment on `preview_tabs.enabled` in
`assets/settings/default.json` words this as "close automatically when
you open another preview tab". That is right for the project-panel path
and carries the same code-navigation caveat as above; I left it alone to
keep this diff to one file, and am happy to align it in a follow-up.

## Self-Review Checklist:

- [x] I've reviewed my own diff for quality, security, and reliability
- [x] Unsafe blocks (if any) have justifying comments — N/A
- [x] The content adheres to Zed's UI standards — N/A, docs only
- [x] Tests cover the new/changed behavior — N/A, no behaviour change;
the docs build is verified locally
- [x] Performance impact has been considered and is acceptable — N/A

---

Release Notes:

- N/A