933273061e
## Summary
- Adds a new concept page (`docs/src/windows-and-projects.md`)
explaining how Zed handles multiple projects in windows
- Fixes the VS Code migration guide which incorrectly stated "Zed does
not support multi-root workspaces"
- Adds cross-links from Getting Started, CLI Reference, and Parallel
Agents docs
## Context
With multi-workspace now universally enabled, the default behavior is:
- **File > Open** opens projects in the current window's sidebar (not a
new window)
- **Cmd+Enter** in Open Recent opens in a new window
- **CLI `-n` flag** forces a new window
The VS Code migration guide was telling users the opposite of reality.
This PR fixes that and provides a central concept page that other docs
can link to.
## Changes
| File | Change |
|------|--------|
| `windows-and-projects.md` | New concept page |
| `SUMMARY.md` | Add to Working with Code section |
| `getting-started.md` | Note about sidebar default + link |
| `migrate/vs-code.md` | Fix "no multi-root" claim → explain sidebar
model |
| `reference/cli.md` | Link to concept page from flags section |
| `ai/parallel-agents.md` | Cross-reference in Multiple Projects section
|
## Test plan
- [ ] Verify page renders correctly on docs site
- [ ] Check all internal links resolve
- [ ] Confirm `{#kb projects::OpenRecent}` renders the correct
keybinding
Release Notes:
- N/A
3.9 KiB
| title | description |
|---|---|
| Getting Started with Zed | Get started with Zed, the fast open-source code editor. Essential commands, environment setup, and navigation basics. |
Getting Started
Zed is an open-source code editor with built-in collaboration and AI tools.
This guide covers the essential commands, environment setup, and navigation basics.
Quick Start
Welcome Page
When you open Zed without a folder, you see the welcome page in the main editor area. The welcome page offers quick actions to open a folder, clone a repository, or view documentation. Once you open a folder or file, the welcome page disappears. If you split the editor into multiple panes, the welcome page appears only in the center pane when empty—other panes show a standard empty state.
To reopen the welcome page, close all items in the center pane or use the command palette to search for "Welcome".
1. Open a Project
Open a folder from the command line:
zed ~/projects/my-app
Or use Cmd+O (macOS) / Ctrl+O (Linux/Windows) to open a folder from within Zed.
By default, new projects open in your current window's threads sidebar. To open in a new window instead, use zed -n ~/projects/my-app or press Cmd+Enter when selecting from Open Recent. See Windows & Projects for more details.
2. Learn the Essential Commands
| Action | macOS | Linux/Windows |
|---|---|---|
| Command palette | Cmd+Shift+P |
Ctrl+Shift+P |
| Go to file | Cmd+P |
Ctrl+P |
| Go to symbol | Cmd+Shift+O |
Ctrl+Shift+O |
| Find in project | Cmd+Shift+F |
Ctrl+Shift+F |
| Toggle terminal | Ctrl+` |
Ctrl+` |
| Open settings | Cmd+, |
Ctrl+, |
The command palette (Cmd+Shift+P) is your gateway to every action in Zed. If you forget a shortcut, search for it there.
3. Configure Your Editor
Open the Settings Editor with Cmd+, (macOS) or Ctrl+, (Linux/Windows). Search for any setting and change it directly.
Common first changes:
- Theme: Press
Cmd+K Cmd+T(macOS) orCtrl+K Ctrl+T(Linux/Windows) to open the theme selector - Font: Search for
buffer_font_familyin Settings - Format on save: Search for
format_on_saveand set toon
4. Set Up Your Language
Zed includes built-in support for many languages. For others, install the extension:
- Open Extensions with
Cmd+Shift+X(macOS) orCtrl+Shift+X(Linux/Windows) - Search for your language
- Click Install
See Languages for language-specific setup instructions.
5. Try AI Features
Zed includes built-in AI assistance. Open the Agent Panel with Cmd+Shift+A (macOS) or Ctrl+Shift+A (Linux/Windows) to start a conversation, or use Cmd+Enter (macOS) / Ctrl+Enter (Linux/Windows) for inline assistance.
See AI Overview to configure providers and learn what's possible.
Coming from Another Editor?
We have dedicated guides for switching from other editors:
- VS Code — Import settings, map keybindings, find equivalent features
- IntelliJ IDEA — Adapt to Zed's approach to navigation and refactoring
- PyCharm — Set up Python development in Zed
- WebStorm — Configure JavaScript/TypeScript workflows
- RustRover — Rust development in Zed
You can also enable familiar keybindings:
- Vim: Enable
vim_modein settings. See Vim Mode. - Helix: Enable
helix_modein settings. See Helix Mode.
Join the Community
Zed is open source. Join us on GitHub or in Discord to contribute code, report bugs, or suggest features.