Katie Geer created
docs/src/SUMMARY.md | 1
docs/src/appearance.md | 2
docs/src/environment.md | 4
docs/src/getting-started.md | 75 +++++++
docs/src/running-testing.md | 6
docs/src/tasks.md | 2
docs/src/terminal.md | 370 +++++++++++++++++++++++++++++++++++++++
7 files changed, 447 insertions(+), 13 deletions(-)
@@ -39,6 +39,7 @@
- [Outline Panel](./outline-panel.md)
- [Tab Switcher](./tab-switcher.md)
- [Running & Testing](./running-testing.md)
+ - [Terminal](./terminal.md)
- [Tasks](./tasks.md)
- [Debugger](./debugger.md)
- [REPL](./repl.md)
@@ -64,7 +64,7 @@ Zed uses three font settings for different contexts:
| ---------------------- | ------------------ |
| `buffer_font_family` | Editor text |
| `ui_font_family` | Interface elements |
-| `terminal.font_family` | Terminal |
+| `terminal.font_family` | [Terminal](./terminal.md) |
Example configuration:
@@ -4,8 +4,8 @@ _**Note**: The following only applies to Zed 0.152.0 and later._
Multiple features in Zed are affected by environment variables:
-- Tasks
-- Built-in terminal
+- [Tasks](./tasks.md)
+- [Built-in terminal](./terminal.md)
- Look-up of language servers
- Language servers
@@ -2,18 +2,77 @@
Welcome to Zed! We are excited to have you. Zed is a powerful multiplayer code editor designed to stay out of your way and help you build what's next.
-## Key Features
+This guide gets you from zero to productive in Zed. You'll learn the essential commands, configure your environment, and find your way around.
-- [Smooth Editing](./editing-code.md): Built in Rust, Zed is responsive and intuitive, with a minimalistic aesthetic and pixel-level editing controls.
-- [Agentic Editing](./ai/overview.md): Use Zed's hosted models to collaborate with agents directly in an IDE. You can also plug into a third-party agent or bring your own keys.
-- [Debugger](./debugger.md): Debug your code in seconds, not hours, with minimal setup required.
-- [Remote Development](./remote-development.md): Offload the heavy lifting to the cloud, so you can focus on writing code.
-- [Extensions](./extensions.md): Leverage Zed's extensions to customize how you work.
+## Quick Start
-## Join the Zed Community
+### 1. Open a Project
+Open a folder from the command line:
+
+```sh
+zed ~/projects/my-app
+```
+
+Or use `Cmd+O` (macOS) / `Ctrl+O` (Linux/Windows) to open a folder from within Zed.
+
+### 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) or `Ctrl+K Ctrl+T` (Linux/Windows) to open the theme selector
+- **Font**: Search for `buffer_font_family` in Settings
+- **Format on save**: Search for `format_on_save` and set to `on`
+
+### 4. Set Up Your Language
+
+Zed includes built-in support for many languages. For others, install the extension:
+
+1. Open Extensions with `Cmd+Shift+X` (macOS) or `Ctrl+Shift+X` (Linux/Windows)
+2. Search for your language
+3. Click Install
+
+See [Languages](./languages.md) 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](./ai/overview.md) to configure providers and learn what's possible.
+
+## Coming from Another Editor?
+
+We have dedicated guides for switching from other editors:
+
+- [VS Code](./migrate/vs-code.md) — Import settings, map keybindings, find equivalent features
+- [IntelliJ IDEA](./migrate/intellij.md) — Adapt to Zed's approach to navigation and refactoring
+- [PyCharm](./migrate/pycharm.md) — Set up Python development in Zed
+- [WebStorm](./migrate/webstorm.md) — Configure JavaScript/TypeScript workflows
+- [RustRover](./migrate/rustrover.md) — Rust development in Zed
+
+You can also enable familiar keybindings:
+
+- **Vim**: Enable `vim_mode` in settings. See [Vim Mode](./vim.md).
+- **Helix**: Enable `helix_mode` in settings. See [Helix Mode](./helix.md).
+
+## Join the Community
Zed is proudly open source, and we get better with every contribution. Join us on GitHub or in Discord to contribute code, report bugs, or suggest features.
-- [Join Discord](https://discord.com/invite/zedindustries)
+- [Discord](https://discord.com/invite/zedindustries)
- [GitHub Discussions](https://github.com/zed-industries/zed/discussions)
- [Zed Reddit](https://www.reddit.com/r/ZedEditor)
@@ -4,6 +4,8 @@ This section covers how to run, test, and debug your code without leaving Zed.
## What's here
+- **[Terminal](./terminal.md)**: Zed's built-in terminal emulator. Open multiple terminals, customize your shell, and integrate with the editor. Tasks and commands run here.
+
- **[Tasks](./tasks.md)**: Define and run shell commands with access to editor context like the current file, selection, or symbol. Use tasks to build, lint, run scripts, or execute any repeatable workflow.
- **[Debugger](./debugger.md)**: Set breakpoints, step through code, and inspect variables using Zed's built-in debugger. Works with C, C++, Go, JavaScript, Python, Rust, TypeScript, and more through the Debug Adapter Protocol.
@@ -12,7 +14,9 @@ This section covers how to run, test, and debug your code without leaving Zed.
## Quick start
-**Run a command**: Press `Cmd+Shift+T` (macOS) or `Ctrl+Shift+T` (Linux/Windows) to open the task picker, then type any shell command.
+**Open a terminal**: Press `` Ctrl+` `` to toggle the terminal panel, or `Ctrl+~` to open a new terminal.
+
+**Run a command**: Press `Cmd+Shift+R` (macOS) or `Ctrl+Shift+R` (Linux/Windows) to open the task picker, then type any shell command.
**Start debugging**: Press `Cmd+Shift+D` (macOS) or `Ctrl+Shift+D` (Linux/Windows) to open the debug panel and select a configuration.
@@ -1,6 +1,6 @@
# Tasks
-Zed supports ways to spawn (and rerun) commands using its integrated terminal to output the results. These commands can read a limited subset of Zed state (such as a path to the file currently being edited or selected text).
+Zed supports ways to spawn (and rerun) commands using its integrated [terminal](./terminal.md) to output the results. These commands can read a limited subset of Zed state (such as a path to the file currently being edited or selected text).
```json [tasks]
[
@@ -0,0 +1,370 @@
+# Terminal
+
+Zed includes a built-in terminal emulator that supports multiple terminal instances, custom shells, and deep integration with the editor.
+
+## Opening Terminals
+
+| Action | macOS | Linux/Windows |
+| ------------------------------- | ------------------------ | ------------------------ |
+| Toggle terminal panel | `` Ctrl+` `` | `` Ctrl+` `` |
+| Open new terminal | `Ctrl+~` | `Ctrl+~` |
+| Open terminal in center | Command palette | Command palette |
+
+You can also open a terminal from the command palette with `terminal panel: toggle` or `workspace: new terminal`.
+
+### Terminal Panel vs Center Terminal
+
+Terminals can open in two locations:
+
+- **Terminal Panel** — Docked at the bottom (default), left, or right of the workspace. Toggle with `` Ctrl+` ``.
+- **Center Pane** — Opens as a regular tab alongside your files. Use `workspace: new center terminal` from the command palette.
+
+## Working with Multiple Terminals
+
+Create additional terminals with `Cmd+N` (macOS) or `Ctrl+N` (Linux/Windows) while focused in the terminal panel. Each terminal appears as a tab in the panel.
+
+Split terminals horizontally with `Cmd+D` (macOS) or `Ctrl+Shift+5` (Linux/Windows).
+
+## Configuring the Shell
+
+By default, Zed uses your system's default shell (from `/etc/passwd` on Unix systems). To use a different shell:
+
+```json [settings]
+{
+ "terminal": {
+ "shell": {
+ "program": "/bin/zsh"
+ }
+ }
+}
+```
+
+To pass arguments to your shell:
+
+```json [settings]
+{
+ "terminal": {
+ "shell": {
+ "with_arguments": {
+ "program": "/bin/bash",
+ "args": ["--login"]
+ }
+ }
+ }
+}
+```
+
+## Working Directory
+
+Control where new terminals start:
+
+| Value | Behavior |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `"current_project_directory"` | Uses the project directory of the currently open file (default) |
+| `"first_project_directory"` | Uses the first project in your workspace |
+| `"always_home"` | Always starts in your home directory |
+| `{ "always": { "directory": "~/projects" } }` | Always starts in a specific directory |
+
+```json [settings]
+{
+ "terminal": {
+ "working_directory": "first_project_directory"
+ }
+}
+```
+
+## Environment Variables
+
+Add environment variables to all terminal sessions:
+
+```json [settings]
+{
+ "terminal": {
+ "env": {
+ "EDITOR": "zed --wait",
+ "MY_VAR": "value"
+ }
+ }
+}
+```
+
+> **Tip:** Use `:` to separate multiple values in a single variable: `"PATH": "/custom/path:$PATH"`
+
+### Python Virtual Environment Detection
+
+Zed can automatically activate Python virtual environments when opening a terminal. By default, it searches for `.env`, `env`, `.venv`, and `venv` directories:
+
+```json [settings]
+{
+ "terminal": {
+ "detect_venv": {
+ "on": {
+ "directories": [".venv", "venv"],
+ "activate_script": "default"
+ }
+ }
+ }
+}
+```
+
+The `activate_script` option supports `"default"`, `"csh"`, `"fish"`, and `"nushell"`.
+
+To disable virtual environment detection:
+
+```json [settings]
+{
+ "terminal": {
+ "detect_venv": "off"
+ }
+}
+```
+
+## Fonts and Appearance
+
+The terminal can use different fonts from the editor:
+
+```json [settings]
+{
+ "terminal": {
+ "font_family": "JetBrains Mono",
+ "font_size": 14,
+ "font_features": {
+ "calt": false
+ },
+ "line_height": "comfortable"
+ }
+}
+```
+
+Line height options:
+
+- `"comfortable"` — 1.618 ratio, good for reading (default)
+- `"standard"` — 1.3 ratio, better for TUI applications with box-drawing characters
+- `{ "custom": 1.5 }` — Custom ratio
+
+### Cursor
+
+Configure cursor appearance:
+
+```json [settings]
+{
+ "terminal": {
+ "cursor_shape": "bar",
+ "blinking": "on"
+ }
+}
+```
+
+Cursor shapes: `"block"`, `"bar"`, `"underline"`, `"hollow"`
+
+Blinking options: `"off"`, `"terminal_controlled"` (default), `"on"`
+
+### Minimum Contrast
+
+Zed adjusts terminal colors to maintain readability. The default value of `45` ensures text remains visible. Set to `0` to disable contrast adjustment and use exact theme colors:
+
+```json [settings]
+{
+ "terminal": {
+ "minimum_contrast": 0
+ }
+}
+```
+
+## Scrolling
+
+Navigate terminal history with these keybindings:
+
+| Action | macOS | Linux/Windows |
+| ----------------- | --------------- | ------------------ |
+| Scroll page up | `Shift+PageUp` or `Cmd+Up` | `Shift+PageUp` |
+| Scroll page down | `Shift+PageDown` or `Cmd+Down` | `Shift+PageDown` |
+| Scroll line up | `Shift+Up` | `Shift+Up` |
+| Scroll line down | `Shift+Down` | `Shift+Down` |
+| Scroll to top | `Shift+Home` or `Cmd+Home` | `Shift+Home` |
+| Scroll to bottom | `Shift+End` or `Cmd+End` | `Shift+End` |
+
+Adjust scroll speed with:
+
+```json [settings]
+{
+ "terminal": {
+ "scroll_multiplier": 3.0
+ }
+}
+```
+
+## Copy and Paste
+
+| Action | macOS | Linux/Windows |
+| ------ | -------- | --------------------- |
+| Copy | `Cmd+C` | `Ctrl+Shift+C` |
+| Paste | `Cmd+V` | `Ctrl+Shift+V` |
+
+### Copy on Select
+
+Automatically copy selected text to the clipboard:
+
+```json [settings]
+{
+ "terminal": {
+ "copy_on_select": true
+ }
+}
+```
+
+### Keep Selection After Copy
+
+By default, text stays selected after copying. To clear the selection:
+
+```json [settings]
+{
+ "terminal": {
+ "keep_selection_on_copy": false
+ }
+}
+```
+
+## Search
+
+Search terminal content with `Cmd+F` (macOS) or `Ctrl+Shift+F` (Linux/Windows). This opens the same search bar used in the editor.
+
+## Vi Mode
+
+Toggle vi-style navigation in the terminal with `Ctrl+Shift+Space`. This allows you to navigate and select text using vi keybindings.
+
+## Clear Terminal
+
+Clear the terminal screen:
+
+- macOS: `Cmd+K`
+- Linux/Windows: `Ctrl+Shift+L`
+
+## Option as Meta (macOS)
+
+For Emacs users or applications that use Meta key combinations, enable Option as Meta:
+
+```json [settings]
+{
+ "terminal": {
+ "option_as_meta": true
+ }
+}
+```
+
+This reinterprets the Option key as Meta, allowing sequences like `Alt+X` to work correctly.
+
+## Alternate Scroll Mode
+
+When enabled, mouse scroll events are converted to arrow key presses in applications like `vim` or `less`:
+
+```json [settings]
+{
+ "terminal": {
+ "alternate_scroll": "on"
+ }
+}
+```
+
+## Path Hyperlinks
+
+Zed detects file paths in terminal output and makes them clickable. `Cmd+Click` (macOS) or `Ctrl+Click` (Linux/Windows) opens the file in Zed, jumping to the line number if one is detected.
+
+Common formats recognized:
+
+- `src/main.rs:42` — Opens at line 42
+- `src/main.rs:42:10` — Opens at line 42, column 10
+- `File "script.py", line 10` — Python tracebacks
+
+## Panel Configuration
+
+### Dock Position
+
+```json [settings]
+{
+ "terminal": {
+ "dock": "bottom"
+ }
+}
+```
+
+Options: `"bottom"` (default), `"left"`, `"right"`
+
+### Default Size
+
+```json [settings]
+{
+ "terminal": {
+ "default_width": 640,
+ "default_height": 320
+ }
+}
+```
+
+### Terminal Button
+
+Hide the terminal button in the status bar:
+
+```json [settings]
+{
+ "terminal": {
+ "button": false
+ }
+}
+```
+
+### Toolbar
+
+Show the terminal title in a breadcrumb toolbar:
+
+```json [settings]
+{
+ "terminal": {
+ "toolbar": {
+ "breadcrumbs": true
+ }
+ }
+}
+```
+
+The title can be set by your shell using the escape sequence `\e]2;Title\007`.
+
+## Integration with Tasks
+
+The terminal integrates with Zed's [task system](./tasks.md). When you run a task, it executes in the terminal. Rerun the last task from a terminal with:
+
+- macOS: `Cmd+Alt+R`
+- Linux/Windows: `Ctrl+Shift+R` or `Alt+T`
+
+## AI Assistance
+
+Get help with terminal commands using inline assist:
+
+- macOS: `Ctrl+Enter`
+- Linux/Windows: `Ctrl+Enter` or `Ctrl+I`
+
+This opens the AI assistant to help explain errors, suggest commands, or troubleshoot issues.
+
+## Sending Text and Keystrokes
+
+For advanced keybinding customization, you can send raw text or keystrokes to the terminal:
+
+```json [keymap]
+{
+ "context": "Terminal",
+ "bindings": {
+ "alt-left": ["terminal::SendText", "\u001bb"],
+ "ctrl-c": ["terminal::SendKeystroke", "ctrl-c"]
+ }
+}
+```
+
+## All Terminal Settings
+
+For the complete list of terminal settings, see the [Terminal section in All Settings](./reference/all-settings.md#terminal).
+
+## What's Next
+
+- [Tasks](./tasks.md) — Run commands and scripts from Zed
+- [REPL](./repl.md) — Interactive code execution
+- [CLI Reference](./reference/cli.md) — Command-line interface for opening files in Zed