Detailed changes
@@ -0,0 +1,264 @@
+---
+name: brand-writer
+description: Write clear, developer-first copy for Zed — leading with facts, grounded in craft.
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion, WebFetch
+user-invocable: true
+---
+
+# Zed Brand Writer
+
+Write in Zed's brand voice: thoughtful, technically grounded, and quietly confident. Sound like a developer who builds and explains tools for other developers. Write like the content on zed.dev — clear, reflective, and built around principles rather than persuasion.
+
+## Invocation
+
+```bash
+/brand-writer # Start a writing session
+/brand-writer "homepage hero copy" # Specify what you're writing
+/brand-writer --review "paste copy" # Review existing copy for brand fit
+```
+
+## Core Voice
+
+You articulate Zed's ideas, capabilities, and philosophy through writing that earns trust. Never try to sell. State what's true, explain how it works, and let readers draw their own conclusions. Speak as part of the same community you're writing for.
+
+**Tone:** Fluent, calm, direct. Sentences flow naturally with complete syntax. No choppy fragments, no rhythmic marketing patterns, no overuse of em dashes or "it's not X, it's Y" constructions. Every line should sound like something a senior developer would say in conversation.
+
+---
+
+## Core Messages
+
+**Code as craft**
+Built from scratch, made with intention. Every feature is fit for purpose, and everything has its place.
+
+**Made for multiplayer**
+Code is collaborative. But today, our conversations happen outside the codebase. In Zed, your team and your AI agents work in the same space, in real time.
+
+**Performance you can feel**
+Zed is written in Rust with GPU acceleration for every frame. When you type or move the cursor, pixels respond instantly. That responsiveness keeps you in flow.
+
+**Always shipping**
+Zed is built for today and improved weekly. Each release moves the craft forward.
+
+**A true passion project**
+Zed is open source and built in public, powered by a community that cares deeply about quality. From the team behind Atom and Tree-sitter.
+
+---
+
+## Writing Principles
+
+1. **Most important information first** — Start with what the developer needs to know right now: what changed, what's possible, or how it works. Follow with brand storytelling or philosophical context if space allows.
+
+2. **Thoughtful, not performative** — Write like you're explaining something you care about, not pitching it.
+
+3. **Explanatory precision** — Share technical detail when it matters. Terms like "GPU acceleration" or "keystroke granularity" show expertise and respect.
+
+4. **Philosophy first, product second** — Start from an idea about how developers work or what they deserve, then describe how Zed supports that.
+
+5. **Natural rhythm** — Vary sentence length. Let ideas breathe. Avoid marketing slogans and forced symmetry.
+
+6. **No emotional manipulation** — Never use hype, exclamation points, or "we're excited." Don't tell the reader how to feel.
+
+---
+
+## Structure
+
+When explaining features or ideas:
+
+1. Lead with the most essential fact or change a developer needs to know.
+2. Explain how Zed addresses it.
+3. Add brand philosophy or context to deepen understanding.
+4. Let the reader infer the benefit — never oversell.
+
+---
+
+## Avoid
+
+- AI/marketing tropes (em dashes, mirrored constructions, "it's not X, it's Y")
+- Buzzwords ("revolutionary," "cutting-edge," "game-changing")
+- Corporate tone or startup voice
+- Fragmented copy and slogans
+- Exclamation points
+- "We're excited to announce..."
+
+---
+
+## Litmus Test
+
+Before finalizing copy, verify:
+
+- Would a senior developer respect this?
+- Does it sound like something from zed.dev?
+- Does it read clearly and naturally aloud?
+- Does it explain more than it sells?
+
+If not, rewrite.
+
+---
+
+## Workflow
+
+### Phase 1: Understand the Ask
+
+Ask clarifying questions:
+
+- What is this for? (homepage, release notes, docs, social, product page)
+- Who's the audience? (prospective users, existing users, developers in general)
+- What's the key message or feature to communicate?
+- Any specific constraints? (character limits, format requirements)
+
+### Phase 2: Gather Context
+
+1. **Load reference files** (auto-loaded from skill folder):
+ - `rubric.md` — 8 scoring criteria for validation
+ - `taboo-phrases.md` — patterns to eliminate
+ - `voice-examples.md` — transformation patterns and fact preservation rules
+
+2. **Search for relevant context** (if needed):
+ - Existing copy on zed.dev for tone reference
+ - Technical details about the feature from docs or code
+ - Related announcements or prior messaging
+
+### Phase 3: Draft (Two-Pass System)
+
+**Pass 1: First Draft with Fact Markers**
+
+Write initial copy. Mark all factual claims with `[FACT]` tags:
+
+- Technical specifications
+- Proper nouns and product names
+- Version numbers and dates
+- Keyboard shortcuts and URLs
+- Attribution and quotes
+
+Example:
+
+> Zed is [FACT: written in Rust] with [FACT: GPU-accelerated rendering at 120fps]. Built by [FACT: the team behind Atom and Tree-sitter].
+
+**Pass 2: Diagnosis**
+
+Score the draft against all 8 rubric criteria:
+
+| Criterion | Score | Issues |
+| -------------------- | ----- | ------ |
+| Technical Grounding | /5 | |
+| Natural Syntax | /5 | |
+| Quiet Confidence | /5 | |
+| Developer Respect | /5 | |
+| Information Priority | /5 | |
+| Specificity | /5 | |
+| Voice Consistency | /5 | |
+| Earned Claims | /5 | |
+
+Scan for taboo phrases. Flag each with line reference.
+
+**Pass 3: Reconstruction**
+
+For any criterion scoring <4 or any taboo phrase found:
+
+1. Identify the specific problem
+2. Rewrite the flagged section
+3. Verify `[FACT]` markers survived
+4. Re-score the rewritten section
+
+Repeat until all criteria score 4+.
+
+### Phase 4: Validation
+
+Present final copy with scorecard:
+
+```
+## Final Copy
+
+[The copy here]
+
+## Scorecard
+
+| Criterion | Score |
+|---------------------|-------|
+| Technical Grounding | 5 |
+| Natural Syntax | 4 |
+| Quiet Confidence | 5 |
+| Developer Respect | 5 |
+| Information Priority| 4 |
+| Specificity | 5 |
+| Voice Consistency | 4 |
+| Earned Claims | 5 |
+| **TOTAL** | 37/40 |
+
+âś… All criteria 4+
+âś… Zero taboo phrases
+âś… All facts preserved
+
+## Facts Verified
+- [FACT: Rust] âś“
+- [FACT: GPU-accelerated] âś“
+- [FACT: 120fps] âś“
+```
+
+**Output formats by context:**
+
+| Context | Format |
+| ------------- | ---------------------------------------------------- |
+| Homepage | H1 + H2 + supporting paragraph |
+| Product page | Section headers with explanatory copy |
+| Release notes | What changed, how it works, why it matters |
+| Docs intro | Clear explanation of what this is and when to use it |
+| Social | Concise, no hashtags, link to learn more |
+
+---
+
+## Review Mode
+
+When invoked with `--review`:
+
+1. **Load reference files** (rubric, taboo phrases, voice examples)
+
+2. **Score the provided copy** against all 8 rubric criteria
+
+3. **Scan for taboo phrases** — list each with line number:
+
+ ```
+ Line 2: "revolutionary" (hype word)
+ Line 5: "—" used 3 times (em dash overuse)
+ Line 7: "We're excited" (empty enthusiasm)
+ ```
+
+4. **Present diagnosis:**
+
+ ```
+ ## Review: [Copy Title]
+
+ | Criterion | Score | Issues |
+ |---------------------|-------|--------|
+ | Technical Grounding | 3 | Vague claims about "performance" |
+ | Natural Syntax | 2 | Triple em dash chain in P2 |
+ | ... | | |
+
+ ### Taboo Phrases Found
+ - Line 2: "revolutionary"
+ - Line 5: "seamless experience"
+
+ ### Verdict
+ ❌ Does not pass (3 criteria below threshold)
+ ```
+
+5. **Offer rewrite** if any criterion scores <4:
+ - Apply transformation patterns from voice-examples.md
+ - Preserve all facts from original
+ - Present rewritten version with new scores
+
+---
+
+## Examples
+
+### Good
+
+> Zed is written in Rust with GPU acceleration for every frame. When you type or move the cursor, pixels respond instantly. That responsiveness keeps you in flow.
+
+### Bad
+
+> We're excited to announce our revolutionary new editor that will change the way you code forever! Say goodbye to slow, clunky IDEs — Zed is here to transform your workflow.
+
+### Fixed
+
+> Zed is a new kind of editor, built from scratch for speed. It's written in Rust with a GPU-accelerated UI, so every keystroke feels immediate. We designed it for developers who notice when their tools get in the way.
@@ -0,0 +1,178 @@
+# Brand Voice Rubric
+
+Score each criterion 1-5. Copy must score **4+ on ALL criteria** to pass.
+
+---
+
+## 1. Technical Grounding (1-5)
+
+Does the copy make specific, verifiable technical claims?
+
+| Score | Description |
+| ----- | ----------------------------------------------------------------------------------------- |
+| 5 | Precise technical details that can be verified (specs, architecture, measurable outcomes) |
+| 4 | Concrete technical claims with clear meaning |
+| 3 | Mix of specific and vague technical references |
+| 2 | Mostly abstract with occasional technical terms |
+| 1 | No technical substance; pure marketing language |
+
+**Examples:**
+
+- âś… "Written in Rust with GPU-accelerated rendering at 120fps"
+- ❌ "Blazingly fast performance that will transform your workflow"
+
+---
+
+## 2. Natural Syntax (1-5)
+
+Does the writing flow like natural speech from a thoughtful developer?
+
+| Score | Description |
+| ----- | --------------------------------------------------------------- |
+| 5 | Varied sentence structure, natural rhythm, reads aloud smoothly |
+| 4 | Mostly natural with minor rhythm issues |
+| 3 | Some AI patterns visible but not dominant |
+| 2 | Obvious structural patterns (parallel triplets, em dash chains) |
+| 1 | Robotic cadence, formulaic construction throughout |
+
+**Red flags:** Em dash overuse, "It's not X, it's Y" constructions, triple parallel lists, sentences all same length.
+
+---
+
+## 3. Quiet Confidence (1-5)
+
+Does the copy state facts without hype or emotional manipulation?
+
+| Score | Description |
+| ----- | -------------------------------------------------------- |
+| 5 | Facts speak for themselves; reader draws own conclusions |
+| 4 | Confident statements with minimal flourish |
+| 3 | Some restraint but occasional hype creeps in |
+| 2 | Frequent superlatives or emotional appeals |
+| 1 | Aggressive marketing tone, telling reader how to feel |
+
+**Examples:**
+
+- âś… "Zed renders every frame on the GPU. You'll notice the difference when you scroll."
+- ❌ "Experience the revolutionary speed that will absolutely transform how you code!"
+
+---
+
+## 4. Developer Respect (1-5)
+
+Does the copy treat the reader as a peer, not a prospect?
+
+| Score | Description |
+| ----- | ------------------------------------------------------- |
+| 5 | Peer-to-peer conversation; assumes technical competence |
+| 4 | Respectful with appropriate technical depth |
+| 3 | Slightly patronizing or oversimplified |
+| 2 | Condescending explanations or forced enthusiasm |
+| 1 | Treats reader as uninformed consumer to be persuaded |
+
+**Examples:**
+
+- âś… "Tree-sitter provides incremental parsing, so syntax highlighting updates as you type."
+- ❌ "Don't worry about the technical details — just know it's fast!"
+
+---
+
+## 5. Information Priority (1-5)
+
+Is the most important information first?
+
+| Score | Description |
+| ----- | --------------------------------------------------- |
+| 5 | Key fact or change leads; context follows naturally |
+| 4 | Important info near top with minor preamble |
+| 3 | Buried lede but recoverable |
+| 2 | Significant buildup before substance |
+| 1 | Key information buried or missing entirely |
+
+**Examples:**
+
+- âś… "Inline completions now stream token-by-token. Previously, you waited for the full response."
+- ❌ "We've been thinking a lot about the developer experience, and after months of work, we're thrilled to share that..."
+
+---
+
+## 6. Specificity (1-5)
+
+Are claims concrete and measurable?
+
+| Score | Description |
+| ----- | -------------------------------------- |
+| 5 | Every claim is specific and verifiable |
+| 4 | Mostly specific with rare abstractions |
+| 3 | Mix of concrete and vague claims |
+| 2 | Mostly abstract benefits |
+| 1 | All claims are vague or unverifiable |
+
+**Examples:**
+
+- âś… "Startup time under 100ms on M1 Macs"
+- ❌ "Lightning-fast startup that respects your time"
+
+---
+
+## 7. Voice Consistency (1-5)
+
+Does the tone remain unified throughout?
+
+| Score | Description |
+| ----- | ------------------------------------------ |
+| 5 | Single coherent voice from start to finish |
+| 4 | Minor tonal shifts that don't distract |
+| 3 | Noticeable drift between sections |
+| 2 | Multiple competing voices |
+| 1 | Jarring tonal inconsistency |
+
+**Check for:** Shifts between casual/formal, technical/marketing, confident/hedging.
+
+---
+
+## 8. Earned Claims (1-5)
+
+Are assertions supported or supportable?
+
+| Score | Description |
+| ----- | ------------------------------------------- |
+| 5 | Every claim can be demonstrated or verified |
+| 4 | Claims are reasonable and mostly verifiable |
+| 3 | Some unsupported assertions |
+| 2 | Multiple unverifiable superlatives |
+| 1 | Bold claims with no backing |
+
+**Examples:**
+
+- âś… "Built by the team behind Atom and Tree-sitter"
+- ❌ "The most advanced editor ever created"
+
+---
+
+## Quick Scoring Template
+
+```
+| Criterion | Score | Notes |
+|---------------------|-------|-------|
+| Technical Grounding | /5 | |
+| Natural Syntax | /5 | |
+| Quiet Confidence | /5 | |
+| Developer Respect | /5 | |
+| Information Priority| /5 | |
+| Specificity | /5 | |
+| Voice Consistency | /5 | |
+| Earned Claims | /5 | |
+| **TOTAL** | /40 | |
+
+Pass threshold: 32/40 (all criteria 4+)
+```
+
+---
+
+## Decision Rules
+
+- **All 4+:** Copy passes. Minor polish optional.
+- **Any 3:** Rewrite flagged sections, re-score.
+- **Any 2 or below:** Full reconstruction required.
+- **Multiple failures:** Start fresh with new approach.
@@ -0,0 +1,195 @@
+# Taboo Phrases
+
+These patterns signal AI-generated or marketing-heavy copy. Eliminate all instances.
+
+---
+
+## Hype Words
+
+Never use these unless quoting someone else:
+
+| Word/Phrase | Why It Fails |
+| ---------------- | ---------------------------------- |
+| revolutionary | Unearned superlative |
+| game-changing | Unearned superlative |
+| cutting-edge | Vague tech buzzword |
+| next-generation | Meaningless without context |
+| blazingly fast | Cliché, unquantified |
+| lightning-fast | Cliché, unquantified |
+| powerful | Vague; what does it do? |
+| robust | Vague; how is it robust? |
+| seamless | Almost never true |
+| frictionless | Almost never true |
+| effortless | Dismisses real complexity |
+| leverage | Corporate jargon |
+| unlock | Marketing manipulation |
+| supercharge | Marketing manipulation |
+| turbocharge | Marketing manipulation |
+| best-in-class | Unverifiable claim |
+| world-class | Unverifiable claim |
+| state-of-the-art | Vague tech buzzword |
+| groundbreaking | Unearned superlative |
+| innovative | Show, don't tell |
+| intuitive | Often means "we didn't explain it" |
+| elegant | Self-congratulatory |
+
+---
+
+## AI Structural Patterns
+
+These constructions reveal AI authorship:
+
+### Em Dash Chains
+
+```
+❌ "Zed is fast — really fast — and it shows in every interaction."
+âś… "Zed is fast. You'll feel it in every interaction."
+```
+
+### "It's not X, it's Y"
+
+```
+❌ "It's not just an editor — it's a complete development environment."
+âś… "Zed combines editing, collaboration, and AI assistance in one workspace."
+```
+
+### Triple Parallel Lists
+
+```
+❌ "Fast. Focused. Collaborative."
+❌ "Write code. Ship faster. Stay in flow."
+âś… "Zed is built for speed and collaboration."
+```
+
+### Colon-Introduced Lists in Prose
+
+```
+❌ "Three things make Zed different: speed, collaboration, and AI."
+âś… "Zed prioritizes speed, real-time collaboration, and AI integration."
+```
+
+### Rhetorical Questions as Openers
+
+```
+❌ "What if your editor could keep up with your thinking?"
+âś… "Zed renders every keystroke instantly."
+```
+
+---
+
+## Empty Enthusiasm
+
+Remove all emotional manipulation:
+
+| Pattern | Problem |
+| --------------------------------- | -------------------------------- |
+| "We're excited to announce..." | Nobody cares about your emotions |
+| "We're thrilled to share..." | Same |
+| "We can't wait for you to try..." | Presumptuous |
+| "You'll love..." | Telling reader how to feel |
+| "Get ready to..." | Marketing hype |
+| "Say goodbye to..." | Cliché setup |
+| "Say hello to..." | Cliché followup |
+| "Finally, an editor that..." | Implies all others failed |
+| "The wait is over" | Presumes anticipation |
+| "Introducing..." (as standalone) | Weak opener |
+
+---
+
+## Vague Benefits
+
+Replace with specific outcomes:
+
+| Vague | Ask Instead |
+| ----------------------- | ------------------------------ |
+| "enhanced productivity" | How much faster? At what task? |
+| "improved workflow" | What specific improvement? |
+| "better experience" | Better how? Measurable? |
+| "streamlined process" | What steps were removed? |
+| "optimized performance" | What metric improved? |
+| "increased efficiency" | What takes less time/effort? |
+| "modern development" | What specific capability? |
+| "next-level coding" | Meaningless |
+| "superior quality" | By what measure? |
+
+---
+
+## Forbidden Punctuation
+
+| Pattern | Rule |
+| ----------- | ---------------------------------- |
+| `!` | Never. Zero exclamation points. |
+| `...` | No dramatic ellipses |
+| ALL CAPS | No shouting for emphasis |
+| `?` as hook | No rhetorical questions as openers |
+| `—` overuse | Max one em dash per paragraph |
+
+---
+
+## Corporate Euphemisms
+
+| Phrase | Problem |
+| ------------------- | ----------------------------- |
+| move the needle | Jargon |
+| synergy | Meme-tier corporate |
+| ecosystem | Often meaningless |
+| paradigm shift | Dated buzzword |
+| holistic approach | Vague |
+| scalable solution | What scales? How? |
+| actionable insights | Corporate speak |
+| value proposition | Never in customer-facing copy |
+| leverage (verb) | Use "use" instead |
+| utilize | Use "use" instead |
+| facilitate | Use clearer verb |
+| empower | Patronizing |
+| enable | Often vague; be specific |
+
+---
+
+## Filler Phrases
+
+Delete without replacement:
+
+- "In today's fast-paced world..."
+- "As developers, we know..."
+- "Let's face it..."
+- "The truth is..."
+- "At the end of the day..."
+- "When it comes to..."
+- "In order to..."
+- "It goes without saying..."
+- "Needless to say..."
+- "As you may know..."
+
+---
+
+## Detection Checklist
+
+Before finalizing, scan for:
+
+1. **Superlatives:** best, most, fastest, only, first, ultimate
+2. **Absolutes:** always, never, every, all, completely, totally
+3. **Hedging:** might, could, potentially, possibly, may help
+4. **Intensifiers:** very, really, extremely, incredibly, absolutely
+5. **Vague quantifiers:** many, numerous, significant, substantial
+
+**Rule:** If you can't prove it or measure it, rewrite it.
+
+---
+
+## Quick Reference
+
+**Instant red flags (auto-fail if present):**
+
+- Any exclamation point
+- "We're excited/thrilled"
+- "Revolutionary" or "game-changing"
+- Em dash used 2+ times in one paragraph
+- "It's not X, it's Y" construction
+
+**Yellow flags (review carefully):**
+
+- Any word from Hype Words list
+- Sentences starting with "And" or "But"
+- Questions in headlines
+- Lists of exactly three items
@@ -0,0 +1,267 @@
+# Voice Transformation Examples
+
+Ten before/after transformations demonstrating Zed's brand voice. Use these as calibration for diagnosis and reconstruction.
+
+---
+
+## 1. Hype to Specifics
+
+**Before (Score: 2/5 Technical Grounding)**
+
+> Zed delivers blazingly fast performance that will revolutionize your coding experience. Our cutting-edge technology ensures you never wait again.
+
+**After (Score: 5/5)**
+
+> Zed is written in Rust with GPU-accelerated rendering. Keystrokes register in under 8ms. Scrolling stays at 120fps even in large files.
+
+**Transformation notes:**
+
+- "blazingly fast" → specific latency numbers
+- "revolutionize" → removed entirely
+- "cutting-edge technology" → actual tech stack
+- "never wait again" → measurable claim
+
+---
+
+## 2. Marketing to Technical
+
+**Before (Score: 2/5 Developer Respect)**
+
+> Don't worry about the complicated stuff — Zed handles it all for you! Just focus on what you do best: writing amazing code.
+
+**After (Score: 5/5)**
+
+> Zed runs language servers in separate processes with automatic crash recovery. If a language server fails, you keep editing while it restarts.
+
+**Transformation notes:**
+
+- Removed patronizing tone ("don't worry")
+- Removed enthusiasm ("amazing")
+- Added technical mechanism
+- Treats reader as capable of understanding
+
+---
+
+## 3. Abstract to Concrete
+
+**Before (Score: 2/5 Specificity)**
+
+> Zed provides a seamless collaborative experience that brings your team together in powerful new ways.
+
+**After (Score: 5/5)**
+
+> Share your workspace with `cmd+shift+c`. Collaborators see your cursor, selections, and edits in real time. Voice chat is built in — no separate call needed.
+
+**Transformation notes:**
+
+- "seamless" → actual UX flow
+- "powerful new ways" → specific features
+- Added keyboard shortcut (concrete entry point)
+- Described what collaboration actually looks like
+
+---
+
+## 4. Em Dash Chains to Natural Flow
+
+**Before (Score: 2/5 Natural Syntax)**
+
+> Zed is fast — really fast — and built for the way developers actually work — not how tools think they should work.
+
+**After (Score: 5/5)**
+
+> Zed is built for speed. We optimized for the workflows developers actually use: jumping between files, searching across projects, editing multiple cursors at once.
+
+**Transformation notes:**
+
+- Removed all em dashes
+- Split into two clear sentences
+- Abstract claim → specific examples
+- "really fast" → removed (show, don't tell)
+
+---
+
+## 5. Enthusiasm to Confidence
+
+**Before (Score: 1/5 Quiet Confidence)**
+
+> We're thrilled to announce Zed 1.0! After years of hard work, we can't wait for you to experience what we've built. You're going to love it!
+
+**After (Score: 5/5)**
+
+> Zed 1.0 is available today. This release includes GPU text rendering, multi-buffer editing, and native collaboration. Download it at zed.dev.
+
+**Transformation notes:**
+
+- Removed all emotional language
+- "thrilled" → deleted
+- "can't wait" → deleted
+- "You're going to love it" → deleted
+- Added substance instead of feelings
+
+---
+
+## 6. "It's Not X, It's Y" Fix
+
+**Before (Score: 2/5 Natural Syntax)**
+
+> Zed isn't just an editor — it's a complete development environment. It's not about features — it's about flow. And it's not slow — it's instant.
+
+**After (Score: 5/5)**
+
+> Zed combines editing, debugging, collaboration, and AI assistance in one application. Everything runs in the same process, so switching between tasks has no context-switch overhead.
+
+**Transformation notes:**
+
+- Eliminated all "it's not X, it's Y" patterns
+- Replaced negation with positive statements
+- Added technical reasoning
+- One clear sentence instead of three choppy ones
+
+---
+
+## 7. Vague Benefits to Specific Outcomes
+
+**Before (Score: 2/5 Specificity)**
+
+> Zed's AI integration enhances your productivity and streamlines your workflow, helping you code smarter and ship faster.
+
+**After (Score: 5/5)**
+
+> Zed runs AI completions inline as you type. Suggestions appear in 200ms. Accept with Tab, reject by continuing to type. The model runs locally or connects to your preferred API.
+
+**Transformation notes:**
+
+- "enhances productivity" → specific UX
+- "streamlines workflow" → actual interaction model
+- "code smarter" → deleted (meaningless)
+- Added technical options (local vs API)
+
+---
+
+## 8. Social Media Cleanup
+
+**Before (Score: 1/5 across multiple criteria)**
+
+> 🚀 Big news! Zed just dropped MASSIVE updates! Multi-file editing, insane AI features, and SO much more. This is a game-changer, folks! Try it now! 🔥
+
+**After (Score: 4/5)**
+
+> Zed 0.150: Multi-buffer editing is here. Edit across files in a single view. AI completions now stream inline. Full changelog at zed.dev/releases.
+
+**Transformation notes:**
+
+- Removed all emoji
+- Removed exclamation points
+- "MASSIVE" → specific features
+- "game-changer" → deleted
+- "SO much more" → link to changelog
+- Added version number for precision
+
+---
+
+## 9. Feature Announcement
+
+**Before (Score: 2/5 Information Priority)**
+
+> We've been listening to your feedback, and after months of development, our incredible team has built something truly special. Today, we're excited to finally share our new terminal integration!
+
+**After (Score: 5/5)**
+
+> Zed now includes a built-in terminal. Open it with `ctrl+\``. Terminals run in splits alongside your editor panes and share the same working directory as your project.
+
+**Transformation notes:**
+
+- Lead with the feature, not the backstory
+- Removed emotional buildup
+- Added keyboard shortcut
+- Described actual behavior
+
+---
+
+## 10. Philosophy Statement
+
+**Before (Score: 3/5 Quiet Confidence)**
+
+> At Zed, we believe that developers deserve better tools. We're passionate about creating the best possible coding experience because we know how frustrating slow, bloated editors can be.
+
+**After (Score: 5/5)**
+
+> Developer tools should be fast, understandable, and collaborative. We built Zed to meet that standard. It's open source so you can verify our work and extend it.
+
+**Transformation notes:**
+
+- "We believe" → direct statement
+- "passionate about" → deleted
+- "best possible" → specific standard
+- "frustrating, slow, bloated" → removed comparison
+- Added concrete proof point (open source)
+
+---
+
+## Fact Preservation Rules
+
+When transforming copy, certain elements must survive unchanged:
+
+### Mark During Diagnosis
+
+Tag factual claims with `[FACT]` during diagnosis phase:
+
+```
+Zed is written in [FACT: Rust] with [FACT: GPU-accelerated rendering].
+It was built by [FACT: the team behind Atom and Tree-sitter].
+```
+
+### Never Change
+
+| Category | Examples |
+| ------------------ | ------------------------------------------ |
+| Technical specs | "120fps", "8ms latency", "Rust" |
+| Proper nouns | "Tree-sitter", "Anthropic", "Claude" |
+| Version numbers | "Zed 1.0", "v0.150" |
+| Keyboard shortcuts | "cmd+shift+c", "ctrl+\`" |
+| URLs | "zed.dev/releases" |
+| Attribution | "built by the team behind Atom" |
+| Dates | "available today", "released January 2024" |
+| Quotes | Any attributed quotation |
+
+### Verification Step
+
+After reconstruction, diff against original `[FACT]` markers:
+
+1. List all facts from original
+2. Confirm each appears in final copy
+3. If a fact was removed, justify why (e.g., not relevant to new scope)
+4. If a fact was changed, flag as error
+
+### Example Verification
+
+**Original with markers:**
+
+> Zed is [FACT: written in Rust] with [FACT: GPU-accelerated rendering at 120fps]. Built by [FACT: the team behind Atom and Tree-sitter].
+
+**Reconstruction:**
+
+> Zed renders every frame on the GPU at 120fps. The Rust codebase prioritizes memory safety without garbage collection pauses. The same engineers who built Atom and Tree-sitter lead development.
+
+**Verification:**
+
+- âś… "Rust" preserved
+- âś… "GPU-accelerated" preserved
+- âś… "120fps" preserved
+- âś… "team behind Atom and Tree-sitter" preserved
+- **Pass**
+
+---
+
+## Transformation Patterns Summary
+
+| Problem | Solution |
+| -------------------- | ---------------------------- |
+| Hype words | Replace with measurements |
+| Em dash chains | Split into sentences |
+| "It's not X, it's Y" | State positively what it is |
+| Enthusiasm | Delete; add substance |
+| Vague benefits | Name specific features |
+| Buried lede | Lead with the news |
+| Rhetorical questions | Make declarative statements |
+| Abstract claims | Add mechanism or measurement |
@@ -180,7 +180,7 @@ In the Agent Profile modal, select a built-in profile, navigate to `Configure To
Zed will store this profile in your settings using the same profile name as the default you overrode.
-All custom profiles can be edited via the UI or by hand under the `agent.profiles` key in your `settings.json` file.
+All custom profiles can be edited via the UI or by hand under the `agent.profiles` key in your settings file.
To delete a custom profile, open the Agent Profile modal, select the profile you want to remove, and click the delete button.
@@ -227,7 +227,7 @@ Autonomous code editing (where the agent writes to files) is only available in t
## Errors and Debugging {#errors-and-debugging}
-In case of any error or strange LLM response behavior, the best way to help the Zed team debug is by reaching for the `agent: open thread as markdown` action and attaching that data as part of your issue on GitHub.
+If you hit an error or unusual LLM behavior, open the thread as Markdown with `agent: open thread as markdown` and attach it to your GitHub issue.
You can also open threads as Markdown by clicking on the file icon button, to the right of the thumbs down button, when focused on the panel's editor.
@@ -240,7 +240,7 @@ You can rate agent responses to help improve Zed's system prompt and tools.
> **_If you don't want data persisted on Zed's servers, don't rate_**.
> We will not collect data for improving our Agentic offering without you explicitly rating responses.
-The best way you can help influence the next change to Zed's system prompt and tools is by rating the LLM's response via the thumbs up/down buttons at the end of every response.
+To help improve Zed's system prompt and tools, rate responses with the thumbs up/down controls at the end of each response.
In case of a thumbs down, a new text area will show up where you can add more specifics about what happened.
You can provide feedback on the thread at any point after the agent responds, and multiple times within the same thread.
@@ -61,7 +61,7 @@ You can assign distinct and specific models for the following AI-powered feature
With the Inline Assistant in particular, you can send the same prompt to multiple models at once.
-Here's how you can customize your `settings.json` to add this functionality:
+Here's how you can customize your settings file ([how to edit](../configuring-zed.md#settings-files)) to add this functionality:
```json [settings]
{
@@ -82,7 +82,7 @@ You can inspect this exclusion list by opening `zed: open default settings` from
}
```
-Users may explicitly exclude additional paths and/or file extensions by adding them to [`edit_predictions.disabled_globs`](https://zed.dev/docs/reference/all-settings#edit-predictions) in their Zed settings.json:
+Users may explicitly exclude additional paths and/or file extensions by adding them to [`edit_predictions.disabled_globs`](https://zed.dev/docs/reference/all-settings#edit-predictions) in their Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -16,7 +16,7 @@ You can configure multiple dimensions of AI usage in Zed:
## Turning AI Off Entirely
-To disable all AI features, add the following to your `settings.json`:
+To disable all AI features, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -15,7 +15,7 @@ The default provider is [Zeta, a proprietary open source and open dataset model]
To use Zeta, [sign in](../authentication.md#what-features-require-signing-in).
Once signed in, predictions appear as you type.
-You can confirm that Zeta is properly configured either by verifying whether you have the following code in your `settings.json`:
+You can confirm that Zeta is properly configured either by verifying whether you have the following code in your settings file:
```json [settings]
"features": {
@@ -244,7 +244,7 @@ Alternatively, if you have Zed set as your provider, consider [using Subtle Mode
### On Buffers
-To not have predictions appear automatically as you type, set this within `settings.json`:
+To not have predictions appear automatically as you type, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -257,7 +257,7 @@ Still, you can trigger edit predictions manually by executing {#action editor::S
### For Specific Languages
-To not have predictions appear automatically as you type when working with a specific language, set this within `settings.json`:
+To not have predictions appear automatically as you type when working with a specific language, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -271,7 +271,7 @@ To not have predictions appear automatically as you type when working with a spe
### In Specific Directories
-To disable edit predictions for specific directories or files, set this within `settings.json`:
+To disable edit predictions for specific directories or files, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -297,7 +297,7 @@ Edit Prediction also works with other providers.
### GitHub Copilot {#github-copilot}
-To use GitHub Copilot as your provider, set this within `settings.json`:
+To use GitHub Copilot as your provider, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -311,7 +311,7 @@ To sign in to GitHub Copilot, click on the Copilot icon in the status bar. A pop
#### Using GitHub Copilot Enterprise
-If your organization uses GitHub Copilot Enterprise, you can configure Zed to use your enterprise instance by specifying the enterprise URI in your `settings.json`:
+If your organization uses GitHub Copilot Enterprise, you can configure Zed to use your enterprise instance by specifying the enterprise URI in your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -346,7 +346,7 @@ To use [Sweep](https://sweep.dev/) as your provider:
Alternatively, click the edit prediction icon in the status bar and select
**Configure Providers** from the menu.
-After adding your API key, Sweep will appear in the provider dropdown in the status bar menu, where you can select it. You can also set it directly in `settings.json`:
+After adding your API key, Sweep will appear in the provider dropdown in the status bar menu, where you can select it. You can also set it directly in your settings file:
```json [settings]
{
@@ -368,7 +368,7 @@ To use [Mercury Coder](https://www.inceptionlabs.ai/) by Inception Labs as your
Alternatively, click the edit prediction icon in the status bar and select
**Configure Providers** from the menu.
-After adding your API key, Mercury Coder will appear in the provider dropdown in the status bar menu, where you can select it. You can also set it directly in `settings.json`:
+After adding your API key, Mercury Coder will appear in the provider dropdown in the status bar menu, where you can select it. You can also set it directly in your settings file:
```json [settings]
{
@@ -390,7 +390,7 @@ To use Mistral's Codestral as your provider:
Alternatively, click the edit prediction icon in the status bar and select
**Configure Providers** from the menu.
-After adding your API key, Codestral will appear in the provider dropdown in the status bar menu, where you can select it. You can also set it directly in `settings.json`:
+After adding your API key, Codestral will appear in the provider dropdown in the status bar menu, where you can select it. You can also set it directly in your settings file:
```json [settings]
{
@@ -230,7 +230,7 @@ From there, you can click to install your preferred agent and it will become ava
### Custom Agents
-You can also add agents through your `settings.json`, by specifying certain fields under `agent_servers`, like so:
+You can also add agents through your settings file ([how to edit](../configuring-zed.md#settings-files)) by specifying certain fields under `agent_servers`, like so:
```json [settings]
{
@@ -47,7 +47,7 @@ This works well with excerpts in [multibuffers](../multibuffers.md).
You can use the Inline Assistant to send the same prompt to multiple models at once.
-Here's how you can customize your `settings.json` to add this functionality:
+Here's how you can customize your settings file ([how to edit](../configuring-zed.md#settings-files)) to add this functionality:
```json [settings]
{
@@ -15,7 +15,7 @@ If you already have an API key for a provider like Anthropic or OpenAI, you can
To add an existing API key to a given provider, go to the Agent Panel settings (`agent: open settings`), look for the desired provider, paste the key into the input, and hit enter.
-> Note: API keys are _not_ stored as plain text in your `settings.json`, but rather in your OS's secure credential storage.
+> Note: API keys are _not_ stored as plain text in your settings file, but rather in your OS's secure credential storage.
## Supported Providers
@@ -69,7 +69,7 @@ With that done, choose one of the three authentication methods:
#### Authentication via Named Profile (Recommended)
1. Ensure you have the AWS CLI installed and configured with a named profile
-2. Open your `settings.json` (`zed: open settings file`) and include the `bedrock` key under `language_models` with the following settings:
+2. Open your settings file (`zed: open settings file`) and include the `bedrock` key under `language_models` with the following settings:
```json [settings]
{
"language_models": {
@@ -185,7 +185,7 @@ Zed will also use the `ANTHROPIC_API_KEY` environment variable if it's defined.
#### Custom Models {#anthropic-custom-models}
-You can add custom models to the Anthropic provider by adding the following to your Zed `settings.json`:
+You can add custom models to the Anthropic provider by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -239,7 +239,7 @@ Zed will also use the `DEEPSEEK_API_KEY` environment variable if it's defined.
#### Custom Models {#deepseek-custom-models}
The Zed agent comes pre-configured to use the latest version for common models (DeepSeek Chat, DeepSeek Reasoner).
-If you wish to use alternate models or customize the API endpoint, you can do so by adding the following to your Zed `settings.json`:
+If you wish to use alternate models or customize the API endpoint, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -296,7 +296,7 @@ Zed will also use the `GEMINI_API_KEY` environment variable if it's defined. See
By default, Zed will use `stable` versions of models, but you can use specific versions of models, including [experimental models](https://ai.google.dev/gemini-api/docs/models/experimental-models). You can configure a model to use [thinking mode](https://ai.google.dev/gemini-api/docs/thinking) (if it supports it) by adding a `mode` configuration to your model. This is useful for controlling reasoning token usage and response speed. If not specified, Gemini will automatically choose the thinking budget.
-Here is an example of a custom Google AI model you could add to your Zed `settings.json`:
+Here is an example of a custom Google AI model you could add to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -351,7 +351,7 @@ Zed will also use the `MISTRAL_API_KEY` environment variable if it's defined.
The Zed agent comes pre-configured with several Mistral models (codestral-latest, mistral-large-latest, mistral-medium-latest, mistral-small-latest, open-mistral-nemo, and open-codestral-mamba).
All the default models support tool use.
-If you wish to use alternate models or customize their parameters, you can do so by adding the following to your Zed `settings.json`:
+If you wish to use alternate models or customize their parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -509,7 +509,7 @@ Zed will also use the `OPENAI_API_KEY` environment variable if it's defined.
#### Custom Models {#openai-custom-models}
The Zed agent comes pre-configured to use the latest version for common models (GPT-5, GPT-5 mini, o4-mini, GPT-4.1, and others).
-To use alternate models, perhaps a preview release, or if you wish to control the request parameters, you can do so by adding the following to your Zed `settings.json`:
+To use alternate models, perhaps a preview release, or if you wish to control the request parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -555,12 +555,12 @@ Custom models will be listed in the model dropdown in the Agent Panel.
Zed supports using [OpenAI compatible APIs](https://platform.openai.com/docs/api-reference/chat) by specifying a custom `api_url` and `available_models` for the OpenAI provider.
This is useful for connecting to other hosted services (like Together AI, Anyscale, etc.) or local models.
-You can add a custom, OpenAI-compatible model either via the UI or by editing your `settings.json`.
+You can add a custom, OpenAI-compatible model either via the UI or by editing your settings file.
To do it via the UI, go to the Agent Panel settings (`agent: open settings`) and look for the "Add Provider" button to the right of the "LLM Providers" section title.
Then, fill up the input fields available in the modal.
-To do it via your `settings.json`, add the following snippet under `language_models`:
+To do it via your settings file ([how to edit](../configuring-zed.md#settings-files)), add the following snippet under `language_models`:
```json [settings]
{
@@ -616,7 +616,7 @@ Zed will also use the `OPENROUTER_API_KEY` environment variable if it's defined.
#### Custom Models {#openrouter-custom-models}
-You can add custom models to the OpenRouter provider by adding the following to your Zed `settings.json`:
+You can add custom models to the OpenRouter provider by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -706,10 +706,10 @@ These routing controls let you fine‑tune cost, capability, and reliability tra
### Vercel v0 {#vercel-v0}
-[Vercel v0](https://v0.app/docs/api/model) is an expert model for generating full-stack apps, with framework-aware completions optimized for modern stacks like Next.js and Vercel.
+[Vercel v0](https://v0.app/docs/api/model) is a model for generating full-stack apps, with framework-aware completions for stacks like Next.js and Vercel.
It supports text and image inputs and provides fast streaming responses.
-The v0 models are [OpenAI-compatible models](/#openai-api-compatible), but Vercel is listed as first-class provider in the panel's settings view.
+The v0 models are [OpenAI-compatible models](/#openai-api-compatible), and Vercel appears as a dedicated provider in the panel's settings view.
To start using it with Zed, ensure you have first created a [v0 API key](https://v0.dev/chat/settings/keys).
Once you have it, paste it directly into the Vercel provider section in the panel's settings view.
@@ -718,7 +718,7 @@ You should then find it as `v0-1.5-md` in the model dropdown in the Agent Panel.
### xAI {#xai}
-Zed has first-class support for [xAI](https://x.ai/) models. You can use your own API key to access Grok models.
+Zed includes a dedicated [xAI](https://x.ai/) provider. You can use your own API key to access Grok models.
1. [Create an API key in the xAI Console](https://console.x.ai/team/default/api-keys)
2. Open the settings view (`agent: open settings`) and go to the **xAI** section
@@ -726,11 +726,11 @@ Zed has first-class support for [xAI](https://x.ai/) models. You can use your ow
The xAI API key will be saved in your keychain. Zed will also use the `XAI_API_KEY` environment variable if it's defined.
-> **Note:** While the xAI API is OpenAI-compatible, Zed has first-class support for it as a dedicated provider. For the best experience, we recommend using the dedicated `x_ai` provider configuration instead of the [OpenAI API Compatible](#openai-api-compatible) method.
+> **Note:** The xAI API is OpenAI-compatible, and Zed also includes a dedicated xAI provider. We recommend using the dedicated `x_ai` provider configuration instead of the [OpenAI API Compatible](#openai-api-compatible) method.
#### Custom Models {#xai-custom-models}
-The Zed agent comes pre-configured with common Grok models. If you wish to use alternate models or customize their parameters, you can do so by adding the following to your Zed `settings.json`:
+The Zed agent comes pre-configured with common Grok models. If you wish to use alternate models or customize their parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -760,7 +760,7 @@ The Zed agent comes pre-configured with common Grok models. If you wish to use a
## Custom Provider Endpoints {#custom-provider-endpoint}
You can use a custom API endpoint for different providers, as long as it's compatible with the provider's API structure.
-To do so, add the following to your `settings.json`:
+To do so, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -7,7 +7,7 @@ description: Install and configure MCP servers in Zed to extend your AI agent wi
Zed uses the [Model Context Protocol](https://modelcontextprotocol.io/) to interact with context servers.
-> The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
+> The Model Context Protocol (MCP) is an open protocol for connecting LLM applications to external tools and data sources through a standard interface.
## Supported Features
@@ -44,7 +44,7 @@ Popular servers available as an extension include:
### As Custom Servers
Creating an extension is not the only way to use MCP servers in Zed.
-You can connect them by adding their commands directly to your `settings.json`, like so:
+You can connect them by adding their commands directly to your settings file ([how to edit](../configuring-zed.md#settings-files)), like so:
```json [settings]
{
@@ -27,7 +27,7 @@ Zed, including AI features, works without sharing data with us and without authe
- [Accounts](../authentication.md): When and why you'd need to authenticate into Zed, how to do so, and what scope we need from you.
-- [Collab](https://zed.dev/faq#data-and-privacy): How Zed's live collaboration works, and how data flows to provide the experience (we don't store your code!).
+- [Collab](https://zed.dev/faq#data-and-privacy): How Zed's live collaboration works, and how data flows to provide the experience (we don't store your code).
## Legal Links
@@ -11,9 +11,9 @@ You can use custom keybindings, multiple cursors, and all the standard editing f
## Text Threads vs. Threads
Text Threads were Zed's original AI interface.
-In May 2025, Zed introduced the current [Agent Panel](./agent-panel.md), optimized for agentic workflows.
+In May 2025, Zed introduced the current [Agent Panel](./agent-panel.md), designed for agentic workflows.
-The key difference: text threads don't support tool calls and many other more moden agentic features.
+The key difference: text threads don't support tool calls and many other more modern agentic features.
They can't autonomously read files, write code, or run commands on your behalf.
Text Threads are for simpler conversational interactions where you send text and receive text responses back.
@@ -203,7 +203,7 @@ Title: Zed-Flavored Rust
_The text in parentheses above are comments and are not part of the rule._
-> **Note:** While you technically _can_ nest a rule within itself, we wouldn't recommend it (in the strongest of terms.) Use at your own risk!
+> **Note:** You can technically nest a rule within itself, but we don't recommend doing so.
By using nested rules, you can create modular and reusable rule components that can be combined in various ways to suit different scenarios.
@@ -8,7 +8,7 @@ For a list of available tools, [see the Tools page](./tools.md).
## Quick Start
-Use Zed's Settings Editor to [configure tool permissions](zed://settings/agent.tool_permissions), or add rules directly to your `settings.json`:
+Use Zed's Settings Editor to [configure tool permissions](zed://settings/agent.tool_permissions), or add rules directly to your settings file:
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: All Actions
+description: "Complete reference of all available actions and commands in Zed."
+---
+
# All Actions
{#ACTIONS_TABLE#}
@@ -1,3 +1,8 @@
+---
+title: Authenticate with Zed
+description: "Sign in to Zed to access collaboration features and AI services."
+---
+
# Authenticate with Zed
Signing in to Zed is not required. You can use most features you'd expect in a code editor without ever doing so. We'll outline the few features that do require signing in, and how to do so, here.
@@ -1,20 +1,26 @@
-# Channels
+---
+title: Channels
+description: "Persistent collaboration rooms in Zed for sharing projects, voice chat, and real-time code editing."
+---
-Channels provide a way to streamline collaborating for software engineers in many ways, but particularly:
+# Channels {#channels}
-- Pairing – when working on something together, you both have your own screen, mouse, and keyboard.
-- Mentoring – it's easy to jump in to someone else's context, and help them get unstuck, without the friction of pushing code up.
-- Refactoring – you can have multiple people join in on large refactoring without fear of conflict.
-- Ambient awareness – you can see what everyone else is working on with no need for status emails or meetings.
+Channels are persistent rooms for team collaboration. Each channel can contain shared projects, voice chat, and collaborative notes.
-Each channel corresponds to an ongoing project or work-stream.
-You can see who's in a channel as their avatars will show up in the sidebar.
-This makes it easy to see what everyone is doing and where to find them if needed.
+Channels support:
-Create a channel by clicking the `+` icon next to the `Channels` text in the collab panel.
-Create a subchannel by right clicking an existing channel and selecting `New Subchannel`.
+- Pairing – each collaborator keeps their own screen, mouse, and keyboard.
+- Mentoring – jump into someone else's context and help without asking them to hand over control.
+- Refactoring – multiple people can join the same large refactor in real time.
+- Ambient awareness – see what teammates are working on without status meetings.
-You can mix channels for your day job, as well as side-projects in your collab panel.
+Each channel usually maps to an ongoing project or workstream.
+You can see who's in a channel because their avatars appear in the Collaboration Panel.
+
+Create a channel by clicking the `+` icon next to the `Channels` text in the Collaboration Panel.
+Create a subchannel by right-clicking an existing channel and selecting `New Subchannel`.
+
+You can keep both work and side-project channels in the Collaboration Panel.
Joining a channel adds you to a shared room where you can work on projects together.
@@ -23,31 +29,29 @@ _Join [our channel tree](https://zed.dev/channel/zed-283) to get an idea of how
## Inviting People
By default, channels you create can only be accessed by you.
-You can invite collaborators by right clicking and selecting `Manage members`.
+You can invite collaborators by right-clicking and selecting `Manage members`.
When you have subchannels nested under others, permissions are inherited.
For instance, adding people to the top-level channel in your channel tree will automatically give them access to its subchannels.
-Once you have added someone, they can either join your channel by clicking on it in their Zed sidebar, or you can share the link to the channel so that they can join directly.
+Once you have added someone, they can either join your channel by clicking on it in their Collaboration Panel, or you can share the link to the channel so that they can join directly.
## Voice Chat
You can mute/unmute your microphone via the microphone icon in the upper right-hand side of the window.
-> Note: When joining a channel, Zed will automatically share your microphone with other users in the call, if your OS allows it.
-> If you'd prefer your microphone to be off when joining a channel, you can do so via the [`mute_on_join`](../reference/all-settings.md#calls) setting.
+> **Note:** When joining a channel, Zed automatically shares your microphone with other users in the call, if your OS allows it. To start muted, use the [`mute_on_join`](../reference/all-settings.md#calls) setting.
## Sharing Projects
After joining a channel, you can share a project over the channel via the `Share` button in the upper right-hand side of the window.
This will allow channel members to edit the code hosted on your machine as though they had it checked out locally.
-When you are editing someone else's project, you still have the full power of the editor at your fingertips; you can jump to definitions, use the AI assistant, and see any diagnostic errors.
-This is extremely powerful for pairing, as one of you can be implementing the current method while the other is reading and researching the correct solution to the next problem.
-And, because you have your own config running, it feels like you're using your own machine.
+When you edit someone else's project, your editor features still work: jump to definition, use AI features, and view diagnostics.
+For pairing, one person can implement while the other reads and validates nearby code.
+Because you keep your own local configuration, the session still feels like your normal setup.
-We aim to eliminate the distinction between local and remote projects as much as possible.
-Collaborators can open, edit, and save files, perform searches, interact with the language server, etc.
+Collaborators can open, edit, and save files, perform searches, and interact with language servers.
Guests have a read-only view of the project, including access to language server info.
### Unsharing a Project
@@ -60,11 +64,11 @@ Collaborators that are currently in that project will be disconnected from the p
Each channel has a Markdown notes file associated with it to keep track of current status, new ideas, or to collaborate on building out the design for the feature that you're working on before diving into code.
-This is similar to a Google Doc, except powered by Zed's collaborative software and persisted to our servers.
+This works like a shared Markdown document backed by Zed's collaboration service.
-Open the channel notes by clicking on the document icon to the right of the channel name in the collaboration panel.
+Open channel notes by clicking the document icon to the right of the channel name in the Collaboration Panel.
-> Note: You can view a channel's notes without joining the channel, if you'd just like to read up on what has been written.
+> **Note:** You can view a channel's notes without joining the channel.
## Following Collaborators
@@ -73,7 +77,7 @@ You can also cycle through collaborators using {#kb workspace::FollowNextCollabo
When you join a project, you'll immediately start following the collaborator that invited you.
-When you are in a pane that is following a collaborator, you will:
+When a pane is following a collaborator, it will:
- follow their cursor and scroll position
- follow them to other files in the same project
@@ -86,14 +90,14 @@ To stop following, simply move your mouse or make an edit via your keyboard.
Following is confined to a particular pane.
When a pane is following a collaborator, it is outlined in their cursor color.
-Avatars of collaborators in the same project as you are in color, and have a cursor color.
+Collaborators in the same project appear in color and include a cursor color.
Collaborators in other projects are shown in gray.
This pane-specific behavior allows you to follow someone in one pane while navigating independently in another and can be an effective layout for some collaboration styles.
### Following a Terminal
-Following is not currently supported in the terminal in the way it is supported in the editor.
+Following in terminals is not currently supported the same way it is in the editor.
As a workaround, collaborators can share their screen and you can follow that instead.
## Screen Sharing
@@ -101,20 +105,19 @@ As a workaround, collaborators can share their screen and you can follow that in
Share your screen with collaborators in the current channel by clicking on the `Share screen` (monitor icon) button in the top right of the title bar.
If you have multiple displays, you can choose which one to share via the chevron to the right of the monitor icon.
-After you've shared your screen, others can click on the `Screen` entry under your name in the collaboration panel to open a tab that always keeps it visible.
+After you've shared your screen, others can click the `Screen` entry under your name in the Collaboration Panel to open a tab that keeps it visible.
If they are following you, Zed will automatically switch between following your cursor in their Zed instance and your screen share, depending on whether you are focused on Zed or another application, like a web browser.
-> Note: Collaborators can see your entire screen when you are screen sharing, so be careful not to share anything you don't want to share.
-> Remember to stop screen sharing when you are finished.
+> **Warning:** Collaborators can see your entire screen when sharing. Stop screen sharing when finished.
## Livestreaming & Guests
-A Channel can also be made Public.
+A channel can also be made public.
This allows anyone to join the channel by clicking on the link.
-Guest users in channels can hear and see everything that is happening, and have read only access to projects and channel notes.
+Guest users in channels can hear and see everything that is happening, and have read-only access to projects and channel notes.
-If you'd like to invite a guest to participate in a channel for the duration of a call you can do so by right clicking on them in the Collaboration Panel.
+If you'd like to invite a guest to participate in a channel for the duration of a call, you can do so by right-clicking them in the Collaboration Panel.
"Allowing Write Access" will allow them to edit any projects shared into the call, and to use their microphone and share their screen if they wish.
## Leaving a Call
@@ -1,11 +1,15 @@
-# Contacts and Private Calls
+---
+title: Contacts and Private Calls
+description: "Add contacts and start private collaboration sessions in Zed."
+---
+
+# Contacts and Private Calls {#contacts}
-Zed allows you to have private calls / collaboration sessions with those in your contacts.
-These calls can be one-on-ones or contain any number of users from your contacts.
+Private calls provide ad-hoc collaboration sessions outside of channels. Add contacts to your list and start calls with one or more people.
## Adding a Contact
-1. In the collaboration panel, click the `+` button next to the `Contacts` section
+1. In the Collaboration Panel, click the `+` button next to the `Contacts` section
1. Search for the contact using their GitHub handle.\
_Note: Your contact must be an existing Zed user who has completed the GitHub authentication sign-in flow._
1. Your contact will receive a notification.
@@ -13,13 +17,13 @@ These calls can be one-on-ones or contain any number of users from your contacts
## Private Calls
-To start up a private call...
+To start a private call:
-1. Click the `...` menu next to an online contact's name in the collaboration panel.
+1. Click the `...` menu next to an online contact's name in the Collaboration Panel.
1. Click `Call <username>`
-Once you've begun a private call, you can add other online contacts by clicking on their name in the collaboration panel.
+Once you've begun a private call, you can add other online contacts by clicking their name in the Collaboration Panel.
---
-_Aside from a few additional features (channel notes, etc.), collaboration in private calls is largely the same as it is in [channels](./channels.md)._
+_Private calls work like [channels](./channels.md), without channel-specific features such as channel notes._
@@ -1,24 +1,21 @@
-# Collaboration
-
-At Zed, we believe that great things are built by great people working together.
-We have designed Zed to help individuals work faster and help teams of people work together more effectively.
+---
+title: Collaboration
+description: "Real-time collaboration in Zed: share projects, edit code together, and communicate with voice chat."
+---
-In Zed, all collaboration happens in the collaboration panel, which can be opened via {#kb collab_panel::ToggleFocus} or `collab panel: toggle focus` from the command palette.
+# Collaboration {#collaboration}
-You will need to [sign in](../authentication.md#signing-in) in order to access features within the collaboration panel.
+Zed supports real-time multiplayer editing. Multiple people can work in the same project simultaneously, seeing each other's cursors and edits as they happen.
-## Collaboration panel
+Open the Collaboration Panel with {#kb collab_panel::ToggleFocus}. You'll need to [sign in](../authentication.md#signing-in) to access collaboration features.
-The collaboration panel is broken down into two sections:
+## Collaboration Panel {#collaboration-panel}
-1. [Channels](./channels.md): Ongoing project rooms where team members can share projects, collaborate on code, and maintain ambient awareness of what everyone is working on.
-1. [Contacts and Private Calls](./contacts-and-private-calls.md): Your contacts list for ad-hoc private collaboration.
+The Collaboration Panel has two sections:
----
+1. [Channels](./channels.md): Persistent project rooms for team collaboration, with shared projects and voice chat.
+2. [Contacts and Private Calls](./contacts-and-private-calls.md): Your contacts list for ad-hoc private sessions.
-> Note: Only collaborate with people that you trust.
-> Since sharing a project gives them access to your local file system, you should not share projects with people you do not trust; they could potentially do some nasty things.
->
-> In the future, we will do more to prevent this type of access beyond the shared project and add more control over what collaborators can do, but for now, only collaborate with people you trust.
+> **Warning:** Sharing a project gives collaborators access to your local file system within that project. Only collaborate with people you trust.
-See our [Data and Privacy FAQs](https://zed.dev/faq#data-and-privacy) for collaboration.
+See the [Data and Privacy FAQs](https://zed.dev/faq#data-and-privacy) for more details.
@@ -5,10 +5,10 @@ description: Access any Zed action from the command palette. Fuzzy search comman
# Command Palette
-The Command Palette is the main way to access pretty much any functionality that's available in Zed. Its keybinding is the first one you should make yourself familiar with. To open it, hit: {#kb command_palette::Toggle}.
+The Command Palette is the main way to access actions in Zed. Its keybinding is one of the first shortcuts to learn: {#kb command_palette::Toggle}.
-Try it! Open the Command Palette and type in `new file`. You should see the list of commands being filtered down to `workspace: new file`. Hit return and you end up with a new buffer.
+To try it, open the Command Palette and type `new file`. The command list should narrow to `workspace: new file`. Press Return to create a new buffer.
Any time you see instructions that include commands of the form `zed: ...` or `editor: ...` and so on that means you need to execute them in the Command Palette.
@@ -1,3 +1,8 @@
+---
+title: Developing Zed
+description: "Guide to building and developing Zed from source."
+---
+
# Developing Zed
See the platform-specific instructions for building Zed from source:
@@ -21,9 +26,9 @@ your password again the next time something changes in the binary.
This quickly becomes annoying and impedes development speed.
That is why, by default, when running a development build of Zed an alternative
-credential provider is used in order to bypass the system keychain.
+credential provider is used to bypass the system keychain.
-> Note: This is **only** the case for development builds. For all non-development
+> **Note:** This is **only** the case for development builds. For all non-development
> release channels the system keychain is always used.
If you need to test something out using the real system keychain in a
@@ -1,38 +1,42 @@
+---
+title: Using a debugger
+description: "Guide to using a debugger for Zed development."
+---
+
# Using a debugger
-> **DISCLAIMER**: This is not documentation for [configuring Zed's debugger](../debugger.md).
-> Rather, it is intended to provide information on how to use a debugger while developing Zed itself to both Zed employees and external contributors.
+> This page is not about [configuring Zed's debugger](../debugger.md).
+> It covers how to use a debugger while developing Zed itself.
## Using Zed's built-in debugger
While the Zed project is open you can open the `New Process Modal` and select the `Debug` tab. There you can see two debug configurations to debug Zed with, one for GDB and one for LLDB. Select the configuration you want and Zed will build and launch the binary.
-Please note, GDB isn't supported on arm Macbooks
+GDB is not supported on Apple Silicon Macs.
## Release build profile considerations
-By default, builds using the release profile (release is the profile used for production builds, i.e. nightly, preview, and stable) include limited debug info.
+By default, builds using the release profile (the profile used for nightly, preview, and stable) include limited debug info.
This is done by setting the `profile.(release).debug` field in the root `Cargo.toml` field to `"limited"`.
-The official documentation for the `debug` field can be found [here](https://doc.rust-lang.org/cargo/reference/profiles.html#debug).
-But the TLDR is that `"limited"` strips type and variable level debug info.
+The official documentation for the `debug` field is [here](https://doc.rust-lang.org/cargo/reference/profiles.html#debug).
+In short, `"limited"` strips type-level and variable-level debug info.
-In release builds, this is done to reduce the binary size, as type and variable level debug info is not required, and does not impact the usability of generated stack traces.
+In release builds, this reduces binary size. Type-level and variable-level debug info is not required for useful stack traces.
-However, while the type and variable level debug info is not required for good stack traces, it is very important for a good experience using debuggers,
-as without the type and variable level debug info, the debugger has no way to resolve local variables, inspect them, format them using pretty-printers, etc.
+However, this data matters when you are actively debugging. Without it, debuggers cannot resolve local variables, inspect values, or format output with pretty-printers.
-Therefore, in order to use a debugger to it's fullest extent when debugging a release build, you must compile a new Zed binary, with full debug info.
+To get the full debugger experience on a release build, compile a Zed binary with full debug info.
-The simplest way to do this, is to use the `--config` flag to override the `debug` field in the root `Cargo.toml` file when running `cargo run` or `cargo build` like so:
+The simplest way is to use `--config` to override the `debug` field in the root `Cargo.toml` when running `cargo run` or `cargo build`:
```sh
cargo run --config 'profile.release.debug="full"'
cargo build --config 'profile.release.debug="full"'
```
-> If you wish to avoid passing the `--config` flag on every invocation of `cargo`. You may also change the section in the [root `Cargo.toml`](https://github.com/zed-industries/zed/blob/main/Cargo.toml)
+> If you do not want to pass `--config` on every `cargo` command, you can also change the section in the [root `Cargo.toml`](https://github.com/zed-industries/zed/blob/main/Cargo.toml)
>
> from
>
@@ -48,66 +52,62 @@ cargo build --config 'profile.release.debug="full"'
> debug = "full"
> ```
>
-> This will ensure all invocations of `cargo run --release` or `cargo build --release` will compile with full debug info.
+> This makes all invocations of `cargo run --release` or `cargo build --release` compile with full debug info.
>
-> **WARNING:** Make sure to avoid committing these changes!
+> **Warning:** Do not commit these changes.
## Running Zed with a shell debugger GDB/LLDB
### Background
-When installing rust through rustup, (the recommended way to do so when developing Zed, see the documentation for getting started on your platform [here](../development.md))
-a few additional scripts are installed and put on your path to assist with debugging binaries compiled with rust.
+When you install Rust through rustup (the recommended setup for Zed development; see your platform guide [here](../development.md)), rustup also installs helper scripts for debugging Rust binaries.
-These are `rust-gdb` and `rust-lldb` respectively.
+These scripts are `rust-gdb` and `rust-lldb`.
-You can read more information about these scripts and why they are useful [here](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html) if you are interested.
+You can read more about these scripts [here](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html).
-However, the summary is that they are simple shell scripts that wrap the standard `gdb` and `lldb` commands, injecting the relevant commands and flags to enable additional
-rust-specific features such as pretty-printers and type information.
+They are wrapper scripts around `gdb` and `lldb` that inject commands and flags for Rust-specific features such as pretty-printers and type info.
-Therefore, in order to use `rust-gdb` or `rust-lldb`, you must have `gdb` or `lldb` installed on your system. If you don't have them installed, you will need to install them in a manner appropriate for your platform.
+To use `rust-gdb` or `rust-lldb`, install `gdb` or `lldb` on your system.
-According to the [previously linked article](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html), "The minimum supported debugger versions are GDB 7.7 and LLDB 310. However, the general rule is: the newer the better." Therefore, it is recommended to install the latest version of `gdb` or `lldb` if possible.
+The [linked article](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html) notes that the minimum supported versions are GDB 7.7 and LLDB 310. In practice, newer versions are usually better.
-> **Note**: `rust-gdb` is not installed by default on Windows, as `gdb` support for windows is not very stable. It is recommended to use `lldb` with `rust-lldb` instead on Windows.
+> **Note**: `rust-gdb` is not installed by default on Windows because `gdb` support there is unstable. Use `rust-lldb` instead.
-If you are unfamiliar with `gdb` or `lldb`, you can learn more about them [here](https://www.gnu.org/software/gdb/) and [here](https://lldb.llvm.org/) respectively.
+If you are new to these tools, see the `gdb` docs [here](https://www.gnu.org/software/gdb/) and the `lldb` docs [here](https://lldb.llvm.org/).
### Usage with Zed
-After following the steps above for including full debug info when compiling Zed,
-You can either run `rust-gdb` or `rust-lldb` on the compiled Zed binary after building it with `cargo build`, by running one of the following commands:
+After enabling full debug info and building with `cargo build`, run `rust-gdb` or `rust-lldb` against the compiled Zed binary:
```
rust-gdb target/debug/zed
rust-lldb target/debug/zed
```
-Alternatively, you can attach to a running instance of Zed (such as an instance of Zed started using `cargo run`) by running one of the following commands:
+You can also attach to a running Zed process (for example, one started with `cargo run`):
```
rust-gdb -p <pid>
rust-lldb -p <pid>
```
-Where `<pid>` is the process ID of the Zed instance you want to attach to.
+`<pid>` is the process ID of the Zed instance you want to attach to.
-To get the process ID of a running Zed instance, you can use your systems process management tools such as `Task Manager` on windows or `Activity Monitor` on macOS.
+To find the PID, use your system's process tools, such as Task Manager on Windows or Activity Monitor on macOS.
-Alternatively, you can run the `ps aux | grep zed` command on macOS and Linux or `Get-Process | Select-Object Id, ProcessName` in an instance of PowerShell on Windows.
+You can also run `ps aux | grep zed` on macOS and Linux, or `Get-Process | Select-Object Id, ProcessName` in PowerShell on Windows.
#### Debugging Panics and Crashes
-Debuggers can be an excellent tool for debugging the cause of panics and crashes in all programs, including Zed.
+Debuggers are useful for finding the cause of panics and crashes, including in Zed.
-By default, when a process that `gdb` or `lldb` is attached to hits an exception such as a panic, the debugger will automatically stop at the point of the panic and allow you to inspect the state of the program.
+By default, when a process attached to `gdb` or `lldb` hits an exception such as a panic, the debugger stops at that point so you can inspect program state.
-Most likely, the point at which the debugger stops will be deep in the rust standard library panic or exception handling code, so you will need to navigate up the stack trace to find the actual cause of the panic.
+The initial stop point is often in Rust standard library panic or exception handling code, so you usually need to walk up the stack to find the root cause.
-This can be accomplished using the `backtrace` command in combination with the `frame select` command in `lldb`, with similar commands available in `gdb`.
+In `lldb`, use `backtrace` with `frame select`. `gdb` provides equivalent commands.
-Once the program is stopped, you will not be able to continue execution as you can before an exception is hit. However, you can jump around to different stack frames, and inspect the values of variables and expressions
-within each frame, which can be very useful in identifying the root cause of the crash.
+After the program stops on the exception, you usually cannot continue normal execution. You can still move between stack frames and inspect variables and expressions, which is often enough to identify the crash cause.
You can find additional information on debugging Zed crashes [here](./debugging-crashes.md).
@@ -1,20 +1,25 @@
+---
+title: Debugging Crashes
+description: "Guide to debugging crashes for Zed development."
+---
+
# Debugging Crashes
-When Zed panics or otherwise crashes, Zed sends a message to a sidecar process which inspects the memory of the crashing editor to create a [minidump](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/getting_started_with_breakpad.md#the-minidump-file-format) file in `~/Library/Logs/Zed` or `$XDG_DATA_HOME/zed/logs`. This minidump can be used to generate backtraces for the stacks of all threads.
+When Zed panics or crashes, it sends a message to a sidecar process that inspects the editor's memory and creates a [minidump](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/getting_started_with_breakpad.md#the-minidump-file-format) in `~/Library/Logs/Zed` or `$XDG_DATA_HOME/zed/logs`. You can use this minidump to generate backtraces for all thread stacks.
-If you have enabled Zed's telemetry these will be uploaded to us when you restart the app. They end up in a [Slack channel](https://zed-industries.slack.com/archives/C0977J9MA1Y) and in [Sentry](https://zed-dev.sentry.io/issues) (both of which are Zed-staff-only).
+If telemetry is enabled, Zed uploads these reports when you restart the app. Reports are sent to a [Slack channel](https://zed-industries.slack.com/archives/C0977J9MA1Y) and to [Sentry](https://zed-dev.sentry.io/issues) (both are Zed-staff-only).
-These crash reports contain rich information; but they are hard to read because they don't contain spans or symbol information. You can still work with them locally by downloading sources and an unstripped binary (or separate symbols file) for your Zed release and running:
+These crash reports include useful data, but they are hard to read without spans or symbol information. You can still analyze them locally by downloading source and an unstripped binary (or separate symbols file) for your Zed release, then running:
```sh
zstd -d ~/.local/share/zed/<uuid>.dmp -o minidump.dmp
minidump-stackwalk minidump.dmp
```
-Alongside the minidump file in your logs dir, there should be a `<uuid>.json` which contains additional metadata like the panic message, span, and system specs.
+Alongside the minidump in your logs directory, you should also see a `<uuid>.json` file with metadata such as the panic message, span, and system specs.
## Using a Debugger
-If you can reproduce the crash consistently, a debugger can be used to inspect the state of the program at the time of the crash, often providing useful insights into the cause of the crash.
+If you can reproduce the crash consistently, use a debugger to inspect program state at the crash point.
-You can read more about setting up and using a debugger with Zed, and specifically for debugging crashes [here](./debuggers.md#debugging-panics-and-crashes)
+For setup details, see [Using a debugger](./debuggers.md#debugging-panics-and-crashes).
@@ -1,6 +1,11 @@
+---
+title: Building Zed for FreeBSD
+description: "Guide to building zed for freebsd for Zed development."
+---
+
# Building Zed for FreeBSD
-Note, FreeBSD is not currently a supported platform, and so this is a work-in-progress.
+FreeBSD is not currently a supported platform, so this guide is a work in progress.
## Repository
@@ -40,7 +45,7 @@ cargo run -p cli
### WebRTC Notice
-Currently, building `webrtc-sys` on FreeBSD fails due to missing upstream support and unavailable prebuilt binaries. As a result, some collaboration features (audio calls and screensharing) that depend on WebRTC are temporarily disabled.
+Building `webrtc-sys` on FreeBSD currently fails due to missing upstream support and unavailable prebuilt binaries. As a result, collaboration features that depend on WebRTC (audio calls and screen sharing) are temporarily disabled.
See [Issue #15309: FreeBSD Support] and [Discussion #29550: Unofficial FreeBSD port for Zed] for more.
@@ -1,8 +1,13 @@
+---
+title: Zed Development: Glossary
+description: "Guide to zed development: glossary for Zed development."
+---
+
# Zed Development: Glossary
-These are some terms and structures frequently used throughout the zed codebase.
+This page defines terms and structures used throughout the Zed codebase.
-This is a best effort list and a work in progress.
+It is a best-effort list and a work in progress.
<!--
TBD: Glossary Improvement
@@ -15,33 +20,32 @@ Questions:
## Naming conventions
-These are generally true for the whole codebase. Note that Name can be anything
-here. An example would be `AnyElement` and `LspStore`.
+These are common naming patterns across the codebase. `Name` is a placeholder
+for any type name, such as `AnyElement` or `LspStore`.
-- `AnyName`: A type erased version of _name_. Think `Box<dyn NameTrait>`.
+- `AnyName`: A type-erased version of _name_. Think `Box<dyn NameTrait>`.
- `NameStore`: A wrapper type which abstracts over whether operations are running locally or on a remote.
## GPUI
### State management
-- `App`: A singleton which holds the full application state including all the entities. Crucially: `App` is not `Send`, which means that `App` only exists on the thread that created it (which is the main/UI thread, usually). Thus, if you see a `&mut App`, know that you're on UI thread.
-- `Context`: A wrapper around the `App` struct with specialized behavior for a specific `Entity`. Think of it as `(&mut App, Entity<V>)`. The specialized behavior is surfaced in the API surface of `Context`. E.g., `App::spawn` takes an `AsyncFnOnce(AsyncApp) -> Ret`, whereas `Context::spawn` takes an `AsyncFnOnce(WeakEntity<V>, AsyncApp) -> Ret`.
-- `AsyncApp`: An owned version of `App` for use in async contexts. This type is _still_ not `Send` (so `AsyncApp` = you're on the main thread) and any use of it may be fallible (to account for the fact that the `App` might've been terminated by the time this closure runs).
- The convenience of `AsyncApp` lies in the fact that you usually interface with `App` via `&mut App`, which would be inconvenient to use with async closures; `AsyncApp` is owned, so you can use it in async closures with no sweat.
-- `AppContext` A trait which abstracts over `App`, `AsyncApp` & `Context` and their Test versions.
-- `Task`: A future running or scheduled to run on the background or foreground
- executor. In contradiction to regular Futures Tasks do not need `.await` to start running. You do need to await them to get the result of the task.
+- `App`: A singleton that holds full application state, including all entities. `App` is not `Send`, so it exists only on the thread that created it (usually the main/UI thread). If you see `&mut App`, you are on the UI thread.
+- `Context`: A wrapper around `App` with specialized behavior for a specific `Entity`. You can think of it as `(&mut App, Entity<V>)`. For example, `App::spawn` takes `AsyncFnOnce(AsyncApp) -> Ret`, while `Context::spawn` takes `AsyncFnOnce(WeakEntity<V>, AsyncApp) -> Ret`.
+- `AsyncApp`: An owned version of `App` for async contexts. It is still not `Send`, so it still runs on the main thread, and operations may fail if the `App` has already terminated.
+ `AsyncApp` exists because `App` is usually accessed as `&mut App`, which is awkward to hold across async boundaries.
+- `AppContext`: A trait that abstracts over `App`, `AsyncApp`, `Context`, and their test variants.
+- `Task`: A future running (or scheduled to run) on a background or foreground executor. Unlike regular futures, tasks do not need `.await` to start. You still need to await them to read their result.
- `Executor`: Used to spawn tasks that run either on the foreground or background thread. Try to run the tasks on the background thread.
- `BackgroundExecutor`: A threadpool running `Task`s.
- `ForegroundExecutor`: The main thread running `Task`s.
- `Entity`: A strong, well-typed reference to a struct which is managed by gpui. Effectively a pointer/map key into the `App::EntityMap`.
- `WeakEntity`: A runtime checked reference to an `Entity` which may no longer exist. Similar to [`std::rc::Weak`](https://doc.rust-lang.org/std/rc/struct.Weak.html).
- `Global`: A singleton type which has only one value, that is stored in the `App`.
-- `Event`: A datatype which can be send by an `Entity` to subscribers
+- `Event`: A data type that can be sent by an `Entity` to subscribers.
- `Action`: An event that represents a user's keyboard input that can be handled by listeners
Example: `file finder: toggle`
-- `Observing`: reacting entities notifying they've changed
+- `Observing`: Reacting to notifications that entities have changed.
- `Subscription`: An event handler that is used to react to the changes of state in the application.
1. Emitted event handling
2. Observing `{new,release,on notify}` of an entity
@@ -71,14 +75,14 @@ h_flex()
## Zed UI
-- `Window`: A struct in zed representing a zed window in your desktop environment (see image below). There can be multiple if you have multiple zed instances open. Mostly passed around for rendering.
+- `Window`: A struct representing a Zed window in your desktop environment (see image below). You can have multiple windows open. This is mostly passed around for rendering.
- `Modal`: A UI element that floats on top of the rest of the UI
- `Picker`: A struct representing a list of items floating on top of the UI (Modal). You can select an item and confirm. What happens on select or confirm is determined by the picker's delegate. (The 'Modal' in the image below is a picker.)
- `PickerDelegate`: A trait used to specialize behavior for a `Picker`. The `Picker` stores the `PickerDelegate` in the field delegate.
- `Center`: The middle of the zed window, the center is split into multiple `Pane`s. In the codebase this is a field on the `Workspace` struct. (see image below).
- `Pane`: An area in the `Center` where we can place items, such as an editor, multi-buffer or terminal (see image below).
-- `Panel`: An `Entity` implementing the `Panel` trait. These can be placed in a `Dock`. In the image below we see the: `ProjectPanel` in the left dock, the `DebugPanel` in the bottom dock, and `AgentPanel` in the right dock. Note `Editor` does not implement `Panel` and hence is not a `Panel`.
-- `Dock`: A UI element similar to a `Pane` which can be opened and hidden. There can be up to 3 docks open at a time, left right and below the center. A dock contains one or more `Panel`s not `Pane`s. (see image).
+- `Panel`: An `Entity` implementing the `Panel` trait. Panels can be placed in a `Dock`. In the image below: `ProjectPanel` is in the left dock, `DebugPanel` is in the bottom dock, and `AgentPanel` is in the right dock. `Editor` does not implement `Panel`.
+- `Dock`: A UI element similar to a `Pane` that can be opened and hidden. Up to three docks can be open at once: left, right, and bottom. A dock contains one or more `Panel`s, not `Pane`s.
<img width="1921" height="1080" alt="Screenshot for the Pane and Dock features" src="https://github.com/user-attachments/assets/2cb1170e-2850-450d-89bb-73622b5d07b2" />
@@ -93,7 +97,7 @@ h_flex()
## Editor
-- `Editor`: _The_ text editor, nearly everything in zed is an `Editor`, even single line inputs. Each pane in the image above contains one or more `Editor` instances.
+- `Editor`: The text editor type. Most editable surfaces in Zed are an `Editor`, including single-line inputs. Each pane in the image above contains one or more `Editor` instances.
- `Workspace`: The root of the window
- `Entry`: A file, dir, pending dir or unloaded dir.
- `Buffer`: The in-memory representation of a 'file' together with relevant data such as syntax trees, git status and diagnostics.
@@ -108,7 +112,7 @@ h_flex()
## Debugger
- `DapStore`: Is an entity that manages debugger sessions
-- `debugger::Session`: Is an entity that manages the lifecycle of a debug session and communication with DAPS
+- `debugger::Session`: An entity that manages the lifecycle of a debug session and communication with DAPs.
- `BreakpointStore`: Is an entity that manages breakpoints states in local and remote instances of Zed
- `DebugSession`: Manages a debug session's UI and running state
- `RunningState`: Directly manages all the views of a debug session
@@ -1,8 +1,13 @@
+---
+title: Building Zed for Linux
+description: "Guide to building zed for linux for Zed development."
+---
+
# Building Zed for Linux
## Repository
-Clone down the [Zed repository](https://github.com/zed-industries/zed).
+Clone the [Zed repository](https://github.com/zed-industries/zed).
## Dependencies
@@ -18,9 +23,9 @@ Clone down the [Zed repository](https://github.com/zed-industries/zed).
### Linkers {#linker}
-On Linux, Rust's default linker is [LLVM's `lld`](https://blog.rust-lang.org/2025/09/18/Rust-1.90.0/). Alternative linkers, especially [Wild](https://github.com/davidlattimore/wild) and [Mold](https://github.com/rui314/mold) can significantly improve clean and incremental build time.
+On Linux, Rust's default linker is [LLVM's `lld`](https://blog.rust-lang.org/2025/09/18/Rust-1.90.0/). Alternative linkers, especially [Wild](https://github.com/davidlattimore/wild) and [Mold](https://github.com/rui314/mold), can improve clean and incremental build times.
-At present Zed uses Mold in CI because it's more mature. For local development Wild is recommended because it's 5-20% faster than Mold.
+Zed currently uses Mold in CI because it is more mature. For local development, Wild is recommended because it is typically 5-20% faster than Mold.
These linkers can be installed with `script/install-mold` and `script/install-wild`.
@@ -73,7 +78,7 @@ You can install a local build on your machine with:
./script/install-linux
```
-This will build zed and the cli in release mode and make them available at `~/.local/bin/zed`, installing .desktop files to `~/.local/share`.
+This builds `zed` and the `cli` in release mode, installs the binary at `~/.local/bin/zed`, and installs `.desktop` files to `~/.local/share`.
> **_Note_**: If you encounter linker errors similar to the following:
>
@@ -92,12 +97,12 @@ This will build zed and the cli in release mode and make them available at `~/.l
> ```
>
> **Cause**:
-> this is caused by known bugs in aws-lc-rs(doesn't support GCC >= 14): [FIPS fails to build with GCC >= 14](https://github.com/aws/aws-lc-rs/issues/569)
+> This is caused by known bugs in aws-lc-rs (no GCC >= 14 support): [FIPS fails to build with GCC >= 14](https://github.com/aws/aws-lc-rs/issues/569)
> & [GCC-14 - build failure for FIPS module](https://github.com/aws/aws-lc/issues/2010)
>
> You can refer to [linux: Linker error for remote_server when using script/install-linux](https://github.com/zed-industries/zed/issues/24880) for more information.
>
-> **Workarounds**:
+> **Workaround**:
> Set the remote server target to `x86_64-unknown-linux-gnu` like so `export REMOTE_SERVER_TARGET=x86_64-unknown-linux-gnu; script/install-linux`
## Wayland & X11
@@ -106,7 +111,7 @@ Zed supports both X11 and Wayland. By default, we pick whichever we can find at
## Notes for packaging Zed
-Thank you for taking on the task of packaging Zed!
+This section is for distribution maintainers packaging Zed.
### Technical requirements
@@ -122,16 +127,14 @@ Zed has two main binaries:
### Other things to note
-At Zed, our priority has been to move fast and bring the latest technology to our users. We've long been frustrated at having software that is slow, out of date, or hard to configure, and so we've built our editor to those tastes.
-
-However, we realize that many distros have other priorities. We want to work with everyone to bring Zed to their favorite platforms. But there is a long way to go:
+Zed moves quickly, and distribution maintainers often have different constraints and priorities. The points below describe current trade-offs:
-- Zed is a fast-moving early-phase project. We typically release 2-3 builds per week to fix user-reported issues and release major features.
+- Zed is a fast-moving project. We typically publish 2-3 builds per week to address reported issues and ship larger changes.
- There are a couple of other `zed` binaries that may be present on Linux systems ([1](https://openzfs.github.io/openzfs-docs/man/v2.2/8/zed.8.html), [2](https://zed.brimdata.io/docs/commands/zed)). If you want to rename our CLI binary because of these issues, we suggest `zedit`, `zeditor`, or `zed-cli`.
-- Zed automatically installs the correct version of common developer tools in the same way as rustup/rbenv/pyenv, etc. We understand this is contentious, [see here](https://github.com/zed-industries/zed/issues/12589).
-- We allow users to install extensions locally and from [zed-industries/extensions](https://github.com/zed-industries/extensions). These extensions may install further tooling as needed, such as language servers. In the long run, we would like to make this safer, [see here](https://github.com/zed-industries/zed/issues/12358).
+- Zed automatically installs versions of common developer tools, similar to rustup/rbenv/pyenv. This behavior is discussed [here](https://github.com/zed-industries/zed/issues/12589).
+- Users can install extensions locally and from [zed-industries/extensions](https://github.com/zed-industries/extensions). Extensions may install additional tools such as language servers. Planned safety improvements are tracked [here](https://github.com/zed-industries/zed/issues/12358).
- Zed connects to several online services by default (AI, telemetry, collaboration). AI and our telemetry can be disabled by your users with their zed settings or by patching our [default settings file](https://github.com/zed-industries/zed/blob/main/assets/settings/default.json).
-- As a result of the above issues, zed currently does not play nice with sandboxes, [see here](https://github.com/zed-industries/zed/pull/12006#issuecomment-2130421220)
+- Because of the points above, Zed currently does not work well with sandboxes. See [this discussion](https://github.com/zed-industries/zed/pull/12006#issuecomment-2130421220).
## Flatpak
@@ -163,21 +166,21 @@ When this zed instance is exited, terminal output will include a command to run
## Perf recording
-How to get a flamegraph with resolved symbols from a running zed instance. Use
-when zed is using a lot of CPU. Not useful for hangs.
+How to get a flamegraph with resolved symbols from a running Zed instance.
+Use this when Zed is using a lot of CPU. It is not useful for hangs.
### During the incident
- Find the PID (process ID) using:
`ps -eo size,pid,comm | grep zed | sort | head -n 1 | cut -d ' ' -f 2`
- Or find the pid of the command zed-editor with the most ram usage in something
+ Or find the PID of `zed-editor` with the highest RAM usage in something
like htop/btop/top.
- Install perf:
On Ubuntu (derivatives) run `sudo apt install linux-tools`.
-- Perf Record:
- run `sudo perf record -p <pid you just found>`, wait a few seconds to gather data then press Ctrl+C. You should now have a perf.data file
+- Perf record:
+ Run `sudo perf record -p <pid you just found>`, wait a few seconds to gather data, then press Ctrl+C. You should now have a `perf.data` file.
- Make the output file user owned:
run `sudo chown $USER:$USER perf.data`
@@ -185,7 +188,7 @@ when zed is using a lot of CPU. Not useful for hangs.
- Get build info:
Run zed again and type `zed: about` in the command pallet to get the exact commit.
-The `data.perf` file can be send to zed together with the exact commit.
+The `perf.data` file can be sent to Zed together with the exact commit.
### Later
@@ -193,7 +196,7 @@ This can be done by Zed staff.
- Build Zed with symbols:
Check out the commit found previously and modify `Cargo.toml`.
- Apply the following diff then make a release build.
+ Apply the following diff, then make a release build.
```diff
[profile.release]
@@ -201,8 +204,8 @@ This can be done by Zed staff.
+debug = "full"
```
-- Add the symbols to perf database:
- `pref buildid-cache -v -a <path to release zed binary>`
+- Add the symbols to the perf database:
+ `perf buildid-cache -v -a <path to release zed binary>`
- Resolve the symbols from the db:
`perf inject -i perf.data -o perf_with_symbols.data`
@@ -1,16 +1,21 @@
+---
+title: Building Zed for macOS
+description: "Guide to building zed for macos for Zed development."
+---
+
# Building Zed for macOS
## Repository
-Clone down the [Zed repository](https://github.com/zed-industries/zed).
+Clone the [Zed repository](https://github.com/zed-industries/zed).
## Dependencies
- Install [rustup](https://www.rust-lang.org/tools/install)
-- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store, or from the [Apple Developer](https://developer.apple.com/download/all/) website. Note this requires a developer account.
+- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store or from the [Apple Developer](https://developer.apple.com/download/all/) website. The Apple Developer download requires a developer account.
-> Ensure you launch Xcode after installing, and install the macOS components, which is the default option.
+> Launch Xcode after installation and install the macOS components (the default option).
- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
@@ -138,7 +143,7 @@ Caused by:
cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
```
-This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
+This file is part of Xcode. Make sure the Xcode command line tools are installed and the path is set correctly:
```sh
xcode-select --install
@@ -169,21 +174,18 @@ This error seems to be caused by OS resource constraints. Installing and running
### Avoiding continual rebuilds
-If you are finding that Zed is continually rebuilding root crates, it may be because
-you are pointing your development Zed at the codebase itself.
+If Zed continually rebuilds root crates, you may be opening the Zed codebase itself in your development build.
This causes problems because `cargo run` exports a bunch of environment
variables which are picked up by the `rust-analyzer` that runs in the development
build of Zed. These environment variables are in turn passed to `cargo check`, which
invalidates the build cache of some of the crates we depend on.
-You can easily avoid running the built binary on the checked-out Zed codebase using `cargo run
-~/path/to/other/project` to ensure that you don't hit this.
+To avoid this, run the built binary against a different project, for example `cargo run ~/path/to/other/project`.
### Speeding up verification
-If you are building Zed a lot, you may find that macOS continually verifies new
-builds which can add a few seconds to your iteration cycles.
+If you build Zed frequently, macOS may keep verifying new builds, which can add a few seconds to each iteration.
To fix this, you can:
@@ -1,3 +1,8 @@
+---
+title: Release Notes
+description: "Guide to release notes for Zed development."
+---
+
# Release Notes
Whenever you open a pull request, the body is automatically populated based on this [pull request template](https://github.com/zed-industries/zed/blob/main/.github/pull_request_template.md).
@@ -10,9 +15,9 @@ Release Notes:
- N/A _or_ Added/Fixed/Improved ...
```
-On Wednesdays, we run a [`get-preview-channel-changes`](https://github.com/zed-industries/zed/blob/main/script/get-preview-channel-changes) script that scrapes `Release Notes` lines from pull requests landing in preview, as documented in our [Release](https://zed.dev/docs/development/release-notes) docs.
+On Wednesdays, we run [`get-preview-channel-changes`](https://github.com/zed-industries/zed/blob/main/script/get-preview-channel-changes), which collects `Release Notes` lines from pull requests landing in preview, as described in the [Release](https://zed.dev/docs/development/release-notes) docs.
-The script outputs everything below the `Release Notes` line, including additional data such as the pull request author (if not a Zed team member) and a link to the pull request.
+The script outputs everything below the `Release Notes` line, including metadata such as the pull request author (if they are not a Zed team member) and a link to the pull request.
If you use `N/A`, the script skips your pull request entirely.
## Guidelines for crafting your `Release Notes` line(s)
@@ -26,4 +31,4 @@ If you use `N/A`, the script skips your pull request entirely.
Don't make the user dig into docs or the pull request to find this information (although it should be included in docs as well).
- For pull requests that are reverts:
- If the item being reverted **has already been shipped**, include a `Release Notes` line explaining why we reverted, as this is a breaking change.
- - If the item being reverted **hasn't been shipped**, edit the original PR's `Release Notes` line to be `N/A`; otherwise, it will be included and the compiler of the release notes may not know to skip it, leading to a potentially-awkward situation where we are stating we shipped something we actually didn't.
+- If the item being reverted **hasn't been shipped**, edit the original PR's `Release Notes` line to `N/A`; otherwise, it will still be included and the release notes compiler may not know to skip it.
@@ -1,22 +1,27 @@
+---
+title: Building Zed for Windows
+description: "Guide to building zed for windows for Zed development."
+---
+
# Building Zed for Windows
> The following commands may be executed in any shell.
## Repository
-Clone down the [Zed repository](https://github.com/zed-industries/zed).
+Clone the [Zed repository](https://github.com/zed-industries/zed).
## Dependencies
- Install [rustup](https://www.rust-lang.org/tools/install)
-- Install either [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the optional components `MSVC v*** - VS YYYY C++ x64/x86 build tools` and `MSVC v*** - VS YYYY C++ x64/x86 Spectre-mitigated libs (latest)` (`v***` is your VS version and `YYYY` is year when your VS was released. Pay attention to the architecture and change it to yours if needed.)
-- Or, if you prefer to have a slimmer installer of only the MSVC compiler tools, you can install the [build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (+libs as above) and the "Desktop development with C++" workload.
- But beware this installation is not automatically picked up by rustup. You must initialize your environment variables by first launching the "developer" shell (cmd/powershell) this installation places in the start menu or in Windows Terminal and then compile.
-- Install Windows 11 or 10 SDK depending on your system, but ensure that at least `Windows 10 SDK version 2104 (10.0.20348.0)` is installed on your machine. You can download it from the [Windows SDK Archive](https://developer.microsoft.com/windows/downloads/windows-sdk/)
+- Install either [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the optional components `MSVC v*** - VS YYYY C++ x64/x86 build tools` and `MSVC v*** - VS YYYY C++ x64/x86 Spectre-mitigated libs (latest)` (`v***` is your VS version and `YYYY` is the release year. Adjust architecture as needed).
+- Or, if you prefer a slimmer installation, install only the [Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (plus the libs above) and the "Desktop development with C++" workload.
+ This setup is not picked up automatically by rustup. Before compiling, initialize environment variables by launching the developer shell (cmd/PowerShell) installed in the Start menu or Windows Terminal.
+- Install the Windows 11 or 10 SDK for your system, and make sure at least `Windows 10 SDK version 2104 (10.0.20348.0)` is installed. You can download it from the [Windows SDK Archive](https://developer.microsoft.com/windows/downloads/windows-sdk/).
- Install [CMake](https://cmake.org/download) (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/)). Or you can install it through Visual Studio Installer, then manually add the `bin` directory to your `PATH`, for example: `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`.
-If you can't compile Zed, make sure that you have at least the following components installed in case of a Visual Studio installation:
+If you cannot compile Zed, make sure a Visual Studio installation includes at least the following components:
```json [settings]
{
@@ -34,7 +39,7 @@ If you can't compile Zed, make sure that you have at least the following compone
}
```
-Or if in case of just Build Tools, the following components:
+If you are using Build Tools only, make sure these components are installed:
```json [settings]
{
@@ -60,7 +65,7 @@ Or if in case of just Build Tools, the following components:
}
```
-The list can be obtained as follows:
+You can export this component list as follows:
- Open the Visual Studio Installer
- Click on `More` in the `Installed` tab
@@ -68,7 +73,7 @@ The list can be obtained as follows:
### Notes
-You should modify the `pg_hba.conf` file in the `data` directory to use `trust` instead of `scram-sha-256` for the `host` method. Otherwise, the connection will fail with the error `password authentication failed`. The `pg_hba.conf` file typically locates at `C:\Program Files\PostgreSQL\17\data\pg_hba.conf`. After the modification, the file should look like this:
+Update `pg_hba.conf` in the `data` directory to use `trust` instead of `scram-sha-256` for the `host` method. Otherwise, the connection fails with `password authentication failed`. The file is typically at `C:\Program Files\PostgreSQL\17\data\pg_hba.conf`. After the change, it should look like this:
```conf
# IPv4 local connections:
@@ -77,14 +82,14 @@ host all all 127.0.0.1/32 trust
host all all ::1/128 trust
```
-Also, if you are using a non-latin Windows version, you must modify the`lc_messages` parameter in the `postgresql.conf` file in the `data` directory to `English_United States.1252` (or whatever UTF8-compatible encoding you have). Otherwise, the database will panic. The `postgresql.conf` file should look like this:
+If you are using a non-Latin Windows locale, set the `lc_messages` parameter in `postgresql.conf` (in the `data` directory) to `English_United States.1252` (or another UTF-8-compatible encoding available on your system). Otherwise, the database may panic. The file should look like this:
```conf
# lc_messages = 'Chinese (Simplified)_China.936' # locale for system error message strings
lc_messages = 'English_United States.1252'
```
-After this, you should restart the `postgresql` service. Press the `win` key + `R` to launch the `Run` window. Type the `services.msc` and hit the `OK` button to open the Services Manager. Then, find the `postgresql-x64-XX` service, right-click on it, and select `Restart`.
+After this, restart the `postgresql` service. Press `Win`+`R` to open the Run dialog, enter `services.msc`, and select **OK**. In Services Manager, find `postgresql-x64-XX`, right-click it, and select **Restart**.
## Building from source
@@ -122,9 +127,9 @@ Please refer to [MSYS2 documentation](https://www.msys2.org/docs/ides-editors/#z
If you set the `RUSTFLAGS` env var, it will override the `rustflags` settings in `.cargo/config.toml` which is required to properly build Zed.
-Since these settings can vary from time to time, the build errors you receive may vary from linker errors, to other stranger errors.
+Because these settings change over time, the resulting build errors may vary from linker failures to other hard-to-diagnose errors.
-If you'd like to add extra rust flags, you may do 1 of the following in `.cargo/config.toml`:
+If you need extra Rust flags, use one of the following approaches in `.cargo/config.toml`:
Add your flags in the build section
@@ -145,7 +150,7 @@ rustflags = [
]
```
-Or, you can create a new `.cargo/config.toml` in the same folder as the Zed repo (see below). This is particularly useful if you are doing CI builds since you don't have to edit the original `.cargo/config.toml`.
+Or, create a new `.cargo/config.toml` in the parent directory of the Zed repo (see below). This is useful in CI because you do not need to edit the repo's original `.cargo/config.toml`.
```
upper_dir
@@ -200,7 +205,7 @@ Caused by:
warning: build failed, waiting for other jobs to finish...
```
-In order to fix this issue, you can manually set the `ZED_RC_TOOLKIT_PATH` environment variable to the RC toolkit path. Usually, you can set it to:
+To fix this issue, manually set the `ZED_RC_TOOLKIT_PATH` environment variable to the RC toolkit path. Usually this is:
`C:\Program Files (x86)\Windows Kits\10\bin\<SDK_version>\x64`.
See this [issue](https://github.com/zed-industries/zed/issues/18393) for more information.
@@ -222,7 +227,7 @@ Caused by:
path too long: 'C:/Users/runneradmin/.cargo/git/checkouts/python-environment-tools-903993894b37a7d2/ffcbf3f/crates/pet-conda/tests/unix/conda_env_without_manager_but_found_in_history/some_other_location/conda_install/conda-meta/python-fastjsonschema-2.16.2-py310hca03da5_0.json'; class=Filesystem (30)
```
-In order to solve this, you can enable longpath support for git and Windows.
+To fix this, enable long-path support for both Git and Windows.
For git: `git config --system core.longpaths true`
@@ -234,13 +239,13 @@ New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name
For more information on this, please see [win32 docs](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell)
-(note that you will need to restart your system after enabling longpath support)
+(You need to restart your system after enabling long-path support.)
### Graphics issues
#### Zed fails to launch
-Currently, Zed uses Vulkan as its graphics API on Windows. However, Vulkan isn't always the most reliable on Windows, so if Zed fails to launch, it's likely a Vulkan-related issue.
+Zed currently uses Vulkan as its graphics API on Windows. If Zed fails to launch, Vulkan is a common cause.
You can check the Zed log at:
`C:\Users\YOU\AppData\Local\Zed\logs\Zed.log`
@@ -252,6 +257,6 @@ If you see messages like:
- `GPU Crashed`
- `ERROR_SURFACE_LOST_KHR`
-Then Vulkan might not be working properly on your system. In most cases, updating your GPU drivers may help resolve this.
+Vulkan may not be working correctly on your system. Updating GPU drivers often resolves this.
If there's nothing Vulkan-related in the logs and you happen to have Bandicam installed, try uninstalling it. Zed is currently not compatible with Bandicam.
@@ -14,11 +14,11 @@ Multiple features in Zed are affected by environment variables:
- Look-up of language servers
- Language servers
-In order to make the best use of these features, it's helpful to understand where Zed gets its environment variables from and how they're used.
+To make the best use of these features, it helps to understand where Zed gets environment variables and how it uses them.
## Where does Zed get its environment variables from?
-How Zed was started — whether it's icon was clicked in the macOS Dock or in a Linux window manager, or whether it was started via the CLI `zed` that comes with Zed — influences which environment variables Zed can use.
+How Zed starts affects which environment variables it can use. That includes launching from the macOS Dock, a Linux window manager, or the `zed` CLI.
### Launched from the CLI
@@ -39,9 +39,9 @@ Starting with Zed 0.152.0, the CLI `zed` will _always_ pass along its environmen
When Zed has been launched via the macOS Dock, or a GNOME or KDE icon on Linux, or an application launcher like Alfred or Raycast, it has no surrounding shell environment from which to inherit its environment variables.
-In order to still have a useful environment, Zed spawns a login shell in the user's home directory and gets its environment. This environment is then set on the Zed _process_. That means all Zed windows and projects will inherit that home directory environment.
+To still have a useful environment, Zed spawns a login shell in the user's home directory and reads its environment. This environment is then set on the Zed _process_, so all Zed windows and projects inherit it.
-Since that can lead to problems for users that require different environment variables for a project (because they use `direnv`, or `asdf`, or `mise`, ... in that project), when opening project, Zed spawns another login shell. This time in the project's directory. The environment from that login shell is _not_ set on the process (because that would mean opening a new project changes the environment for all Zed windows). Instead, the environment is stored and passed along when running tasks, opening terminals, or spawning language servers.
+Since that can lead to problems for users who need different environment variables per project (for example with `direnv`, `asdf`, or `mise`), Zed spawns another login shell when opening a project. This second shell runs in the project's directory. The environment from that shell is _not_ set on the process, because opening a new project would otherwise change the environment for all Zed windows. Instead, that environment is stored and passed along when running tasks, opening terminals, or spawning language servers.
## Where and how are environment variables used?
@@ -56,7 +56,7 @@ The variables from (2) are used explicitly, depending on the feature.
### Tasks
-Tasks are spawned with an combined environment. In order of precedence (low to high, with the last overwriting the first):
+Tasks are spawned with a combined environment. In order of precedence (low to high, with the last overwriting the first):
- the Zed process environment
- if the project was opened from the CLI: the CLI environment
@@ -65,7 +65,7 @@ Tasks are spawned with an combined environment. In order of precedence (low to h
### Built-in terminal
-Built-in terminals, like tasks, are spawned with an combined environment. In order of precedence (low to high):
+Built-in terminals, like tasks, are spawned with a combined environment. In order of precedence (low to high):
- the Zed process environment
- if the project was opened from the CLI: the CLI environment
@@ -82,7 +82,7 @@ For some languages the language server adapters lookup the binary in the user's
- C
- TypeScript
-For this look-up, Zed uses the following the environment:
+For this look-up, Zed uses the following environment:
- if the project was opened from the CLI: the CLI environment
- if the project was not opened from the CLI: the project environment variables obtained by running a login shell in the project's root folder
@@ -93,5 +93,5 @@ After looking up a language server, Zed starts them.
These language server processes always inherit Zed's process environment. But, depending on the language server look-up, additional environment variables might be set or overwrite the process environment.
-- If the language server was found in the project environment's `$PATH`, then the project environment's is passed along to the language server process. Where the project environment comes from depends on how the project was opened, via CLI or not. See previous point on look-up of language servers.
-- If the language servers was not found in the project environment, Zed tries to install it globally and start it globally. In that case, the process will inherit Zed's process environment, and — if the project was opened via ClI — from the CLI.
+- If the language server was found in the project environment's `$PATH`, then that project environment is passed along to the language server process. Where the project environment comes from depends on how the project was opened (via CLI or not). See the previous section on language server look-up.
+- If the language server was not found in the project environment, Zed tries to install and start it globally. In that case, the process inherits Zed's process environment and, if the project was opened via CLI, the CLI environment.
@@ -1,3 +1,8 @@
+---
+title: Extensions
+description: "Extend Zed with themes, language support, AI tools, and more through the extension system."
+---
+
# Extensions
Zed lets you add new functionality using user-defined extensions.
@@ -1,3 +1,8 @@
+---
+title: Agent Server Extensions
+description: "Agent Server Extensions for Zed extensions."
+---
+
# Agent Server Extensions
<div class="warning">
@@ -10,7 +15,7 @@ At some point in the near future, Agent Server extensions will be deprecated.
</div>
Agent Servers are programs that provide AI agent implementations through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
-Agent Server Extensions let you package up an Agent Server so that users can install the extension and have your agent easily available to use in Zed.
+Agent Server Extensions let you package an Agent Server so users can install the extension and use your agent in Zed.
You can see the current Agent Server extensions either by opening the Extensions tab in Zed (execute the `zed: extensions` command) and changing the filter from `All` to `Agent Servers`, or by visiting [the Zed website](https://zed.dev/extensions?filter=agent-servers).
@@ -128,7 +133,7 @@ GitHub Releases are a reliable way to distribute agent server binaries:
## SHA-256 Hashes
-It's good for security to include SHA-256 hashes of your archives in `extension.toml`. Here's how to generate it:
+For better supply-chain security, include SHA-256 hashes of your archives in `extension.toml`. Here's how to generate one:
### macOS and Linux
@@ -163,20 +168,16 @@ To test your Agent Server Extension:
## Icon Guideline
-In case your agent server has a logo, we highly recommend adding it as an SVG icon.
-For optimal display, follow these guidelines:
+If your agent server has a logo, add it as an SVG icon.
+For consistent rendering, follow these guidelines:
-- Make sure you resize your SVG to fit a 16x16 bounding box, with a padding of around one or two pixels
-- Ensure you have a clean SVG code by processing it through [SVGOMG](https://jakearchibald.github.io/svgomg/)
-- Avoid including icons with gradients as they will often make the SVG more complicated and possibly not render perfectly
+- Resize your SVG to fit a 16x16 bounding box with around one or two pixels of padding
+- Keep the SVG markup clean by processing it through [SVGOMG](https://jakearchibald.github.io/svgomg/)
+- Avoid gradients, which often increase SVG complexity and can render inconsistently
Note that we'll automatically convert your icon to monochrome to preserve Zed's design consistency.
(You can still use opacity in different paths of your SVG to add visual layering.)
----
-
-This is all you need to distribute an agent server through Zed's extension system!
-
## Publishing
Once your extension is ready, see [Publishing your extension](./developing-extensions.md#publishing-your-extension) to learn how to submit it to the Zed extension registry.
@@ -1,3 +1,8 @@
+---
+title: Extension Capabilities
+description: "Extension Capabilities for Zed extensions."
+---
+
# Extension Capabilities
The operations that Zed extensions are able to perform are governed by a capability system.
@@ -10,7 +15,7 @@ This is controlled via the `granted_extension_capabilities` setting.
Restricting or removing a capability will cause an error to be returned when an extension attempts to call the corresponding extension API without sufficient capabilities.
-For instance, if you wanted to restrict downloads to just files from GitHub, you could modify `host` for the `download_file` capability:
+For example, to restrict downloads to files from GitHub, set `host` for the `download_file` capability:
```diff
{
@@ -1,3 +1,8 @@
+---
+title: Debugger Extensions
+description: "Debugger Extensions for Zed extensions."
+---
+
# Debugger Extensions
[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol) Servers can be exposed as extensions for use in the [debugger](../debugger.md).
@@ -30,7 +35,7 @@ impl zed::Extension for MyExtension {
This method should return the command to start up a debug adapter protocol server, along with any arguments or environment variables necessary for it to function.
-If you need to download the DAP server from an external source—like GitHub Releases or npm—you can also do that in this function. Make sure to check for updates only periodically, as this function is called whenever a user spawns a new debug session with your debug adapter.
+If you need to download the DAP server from an external source (GitHub Releases, npm, etc.), you can also do that in this function. Make sure to check for updates only periodically, as this function is called whenever a user spawns a new debug session with your debug adapter.
You must also implement `dap_request_kind`. This function is used to determine whether a given debug scenario will _launch_ a new debuggee or _attach_ to an existing one.
We also use it to determine that a given debug scenario requires running a _locator_.
@@ -67,7 +72,7 @@ A locator locates the debug target and figures out how to spawn a debug session
> Your extension can define its own debug locators even if it does not expose a debug adapter. We strongly recommend doing so when your extension already exposes language tasks, as it allows users to spawn a debug session without having to manually configure the debug adapter.
-Locators can (but don't have to) be agnostic to the debug adapter they are used with. They are simply responsible for locating the debug target and figuring out how to spawn a debug session for it. This allows for a more flexible and extensible debugging experience.
+Locators can (but don't have to) be agnostic to the debug adapter they are used with. They are responsible for locating the debug target and figuring out how to spawn a debug session for it. This lets extensions share locator logic across adapters.
Your extension can define one or more debug locators. Each debug locator must be registered in the `extension.toml`:
@@ -108,9 +113,9 @@ Note however that you do _not_ need to go through a 2-phase resolution; if you c
## Available Extensions
-Check out all the DAP servers that have already been exposed as extensions [on Zed's site](https://zed.dev/extensions?filter=debug-adapters).
+See DAP servers published as extensions [on Zed's site](https://zed.dev/extensions?filter=debug-adapters).
-We recommend taking a look at their repositories as a way to understand how they are generally created and structured.
+Review their repositories to see common implementation patterns and structure.
## Testing
@@ -1,8 +1,15 @@
-# Developing Extensions
+---
+title: Developing Extensions
+description: "Create Zed extensions: languages, themes, debuggers, slash commands, and more."
+---
-## Extension Features
+# Developing Extensions {#developing-extensions}
-Extensions are able to provide the following features to Zed:
+Zed extensions are Git repositories containing an `extension.toml` manifest. They can provide languages, themes, debuggers, slash commands, and MCP servers.
+
+## Extension Features {#extension-features}
+
+Extensions can provide:
- [Languages](./languages.md)
- [Debuggers](./debugger-extensions.md)
@@ -21,7 +28,7 @@ When developing an extension, you can use it in Zed without needing to publish i
From the extensions page, click the `Install Dev Extension` button (or the {#action zed::InstallDevExtension} action) and select the directory containing your extension.
-If you need to troubleshoot, you can check the Zed.log ({#action zed::OpenLog}) for additional output. For debug output, close and relaunch zed with the `zed --foreground` from the command line which show more verbose INFO level logging.
+If you need to troubleshoot, check Zed.log ({#action zed::OpenLog}) for additional output. For debug output, close and relaunch Zed from the command line with `zed --foreground`, which shows more verbose INFO-level logs.
If you already have the published version of the extension installed, the published version will be uninstalled prior to the installation of the dev extension. After successful installation, the `Extensions` page will indicate that the upstream extension is "Overridden by dev extension".
@@ -36,11 +43,11 @@ name = "My extension"
version = "0.0.1"
schema_version = 1
authors = ["Your Name <you@example.com>"]
-description = "My cool extension"
+description = "Example extension"
repository = "https://github.com/your-name/my-zed-extension"
```
-> Note: If you are working on a theme extension with the intend of publishing it later, is is recommended that you suffix your theme's extension ID with `-theme`. This might otherwise be raised during the process of [releasing your extension](#publishing-your-extension).
+> **Note:** If you are working on a theme extension with the intent to publish it later, suffix your theme extension ID with `-theme`. Otherwise, this may be raised during [extension publishing](#publishing-your-extension).
In addition to this, there are several other optional files and directories that can be used to add functionality to a Zed extension. An example directory structure of an extension that provides all capabilities is as follows:
@@ -99,7 +106,7 @@ zed::register_extension!(MyExtension);
1. Fork the repo
-> Note: It is very helpful if you fork the `zed-industries/extensions` repo to a personal GitHub account instead of a GitHub organization, as this allows Zed staff to push any needed changes to your PR to expedite the publishing process.
+> **Note:** It is very helpful if you fork the `zed-industries/extensions` repo to a personal GitHub account instead of a GitHub organization, as this allows Zed staff to push any needed changes to your PR to expedite the publishing process.
2. Clone the repo to your local machine
@@ -1,6 +1,11 @@
+---
+title: Icon Themes
+description: "Icon Themes for Zed extensions."
+---
+
# Icon Themes
-Extensions may provide icon themes in order to change the icons Zed uses for folders and files.
+Extensions may provide icon themes to change the icons Zed uses for folders and files.
## Example extension
@@ -11,11 +16,11 @@ The [Material Icon Theme](https://github.com/zed-extensions/material-icon-theme)
There are two important directories for an icon theme extension:
- `icon_themes`: This directory will contain one or more JSON files containing the icon theme definitions.
-- `icons`: This directory contains the icon assets that will be distributed with the extension. You can created subdirectories in this directory, if so desired.
+- `icons`: This directory contains the icon assets distributed with the extension. You can create subdirectories in this directory as needed.
Each icon theme file should adhere to the JSON schema specified at [`https://zed.dev/schema/icon_themes/v0.3.0.json`](https://zed.dev/schema/icon_themes/v0.3.0.json).
-Here is an example of the structure of an icon theme:
+Here is an example icon theme structure:
```json [icon-theme]
{
@@ -61,7 +66,7 @@ Here is an example of the structure of an icon theme:
Each icon path is resolved relative to the root of the extension directory.
-In this example, the extension would have a structure like so:
+In this example, the extension would have this structure:
```
extension.toml
@@ -1,8 +1,13 @@
-# Installing Extensions
+---
+title: Installing Extensions
+description: "Browse, install, and manage extensions from the Zed Extension Gallery."
+---
-You can search for extensions by launching the Zed Extension Gallery by pressing {#kb zed::Extensions} , opening the command palette and selecting {#action zed::Extensions} or by selecting "Zed > Extensions" from the menu bar.
+# Installing Extensions {#installing-extensions}
-Here you can view the extensions that you currently have installed or search and install new ones.
+Extensions add functionality to Zed, including languages, themes, and AI tools. Browse and install them from the Extension Gallery.
+
+Open the Extension Gallery with {#kb zed::Extensions}, or select "Zed > Extensions" from the menu bar.
## Installation Location
@@ -15,6 +20,6 @@ This directory contains two subdirectories:
- `installed`, which contains the source code for each extension.
- `work` which contains files created by the extension itself, such as downloaded language servers.
-## Auto installing
+## Auto-installing
To automate extension installation/uninstallation see the docs for [auto_install_extensions](../reference/all-settings.md#auto-install-extensions).
@@ -1,3 +1,8 @@
+---
+title: Language Extensions
+description: "Overview of programming language support in Zed, including built-in and extension-based languages."
+---
+
# Language Extensions
Language support in Zed has several components:
@@ -26,7 +31,7 @@ line_comments = ["# "]
- `line_comments` is an array of strings that are used to identify line comments in the language. This is used for the `editor::ToggleComments` keybind: {#kb editor::ToggleComments} for toggling lines of code.
- `tab_size` defines the indentation/tab size used for this language (default is `4`).
- `hard_tabs` whether to indent with tabs (`true`) or spaces (`false`, the default).
-- `first_line_pattern` is a regular expression, that in addition to `path_suffixes` (above) or `file_types` in settings can be used to match files which should use this language. For example Zed uses this to identify Shell Scripts by matching the [shebangs lines](https://github.com/zed-industries/zed/blob/main/crates/languages/src/bash/config.toml) in the first line of a script.
+- `first_line_pattern` is a regular expression that can be used alongside `path_suffixes` (above) or `file_types` in settings to match files that should use this language. For example, Zed uses this to identify Shell Scripts by matching [shebang lines](https://github.com/zed-industries/zed/blob/main/crates/languages/src/bash/config.toml) in the first line of a script.
- `debuggers` is an array of strings that are used to identify debuggers in the language. When launching a debugger's `New Process Modal`, Zed will order available debuggers by the order of entries in this array.
<!--
@@ -90,7 +95,7 @@ Here's an example from a `highlights.scm` for JSON:
(number) @number
```
-This query marks strings, object keys, and numbers for highlighting. The following is a comprehensive list of captures supported by themes:
+This query marks strings, object keys, and numbers for highlighting. The following is the full list of captures supported by themes:
| Capture | Description |
| ------------------------ | -------------------------------------- |
@@ -237,7 +242,7 @@ The `overrides.scm` file defines syntactic _scopes_ that can be used to override
For example, there is a language-specific setting called `word_characters` that controls which non-alphabetic characters are considered part of a word, for example when you double click to select a variable. In JavaScript, "$" and "#" are considered word characters.
-There is also a language-specific setting called `completion_query_characters` that controls which characters trigger autocomplete suggestions. In JavaScript, when your cursor is within a _string_, "-" is should be considered a completion query character. To achieve this, the JavaScript `overrides.scm` file contains the following pattern:
+There is also a language-specific setting called `completion_query_characters` that controls which characters trigger autocomplete suggestions. In JavaScript, when your cursor is within a _string_, `-` should be considered a completion query character. To achieve this, the JavaScript `overrides.scm` file contains the following pattern:
```scheme
[
@@ -266,7 +271,7 @@ brackets = [
#### Range inclusivity
-By default, the ranges defined in `overrides.scm` are _exclusive_. So in the case above, if you cursor was _outside_ the quotation marks delimiting the string, the `string` scope would not take effect. Sometimes, you may want to make the range _inclusive_. You can do this by adding the `.inclusive` suffix to the capture name in the query.
+By default, the ranges defined in `overrides.scm` are _exclusive_. So in the case above, if your cursor was _outside_ the quotation marks delimiting the string, the `string` scope would not take effect. Sometimes, you may want to make the range _inclusive_. You can do this by adding the `.inclusive` suffix to the capture name in the query.
For example, in JavaScript, we also disable auto-closing of single quotes within comments. And the comment scope must extend all the way to the newline after a line comment. To achieve this, the JavaScript `overrides.scm` contains the following pattern:
@@ -280,7 +285,7 @@ The `textobjects.scm` file defines rules for navigating by text objects. This wa
Vim provides two levels of granularity for navigating around files. Section-by-section with `[]` etc., and method-by-method with `]m` etc. Even languages that don't support functions and classes can work well by defining similar concepts. For example CSS defines a rule-set as a method, and a media-query as a class.
-For languages with closures, these typically should not count as functions in Zed. This is best-effort however, as languages like JavaScript do not syntactically differentiate syntactically between closures and top-level function declarations.
+For languages with closures, these typically should not count as functions in Zed. This is best-effort, however, because languages like JavaScript do not syntactically differentiate between closures and top-level function declarations.
For languages with declarations like C, provide queries that match `@class.around` or `@function.around`. The `if` and `ic` text objects will default to these if there is no inside.
@@ -411,7 +416,7 @@ Zed supports syntax highlighting using semantic tokens from the attached languag
```json [settings]
{
- // Enable semantic tokens globally, backin with tree-sitter highlights for each language:
+ // Enable semantic tokens globally, backed by tree-sitter highlights for each language:
"semantic_tokens": "combined",
// Or, specify per-language:
"languages": {
@@ -1,3 +1,8 @@
+---
+title: MCP Server Extensions
+description: "MCP Server Extensions for Zed extensions."
+---
+
# MCP Server Extensions
[Model Context Protocol servers](../ai/mcp.md) can be exposed as extensions for use in the Agent Panel.
@@ -31,13 +36,13 @@ impl zed::Extension for MyExtension {
This method should return the command to start up an MCP server, along with any arguments or environment variables necessary for it to function.
-If you need to download the MCP server from an external source—like GitHub Releases or npm—you can also do that in this function.
+If you need to download the MCP server from an external source (GitHub Releases, npm, etc.), you can also do that in this function.
## Available Extensions
-Check out all the MCP servers that have already been exposed as extensions [on Zed's site](https://zed.dev/extensions?filter=context-servers).
+See MCP servers published as extensions [on Zed's site](https://zed.dev/extensions?filter=context-servers).
-We recommend taking a look at their repositories as a way to understand how they are generally created and structured.
+Review their repositories to see common implementation patterns and structure.
## Testing
@@ -1,3 +1,8 @@
+---
+title: Slash Commands
+description: "Slash Commands for Zed extensions."
+---
+
# Slash Commands
Extensions may provide slash commands for use in the Assistant.
@@ -1,10 +1,15 @@
+---
+title: Themes
+description: "Themes for Zed extensions."
+---
+
# Themes
The `themes` directory in an extension should contain one or more theme files.
Each theme file should adhere to the JSON schema specified at [`https://zed.dev/schema/themes/v0.2.0.json`](https://zed.dev/schema/themes/v0.2.0.json).
-See [this blog post](https://zed.dev/blog/user-themes-now-in-preview) for more details about creating themes.
+See [this blog post](https://zed.dev/blog/user-themes-now-in-preview) for additional background on creating themes.
## Theme JSON Structure
@@ -16,7 +21,7 @@ A Zed theme consists of a Theme Family object including:
- `author`: The name of the author of the theme family
- `themes`: An array of Themes belonging to the theme family
-The core components a Theme object include:
+The core components of a Theme object include:
1. Theme Metadata:
@@ -54,5 +59,5 @@ The core components a Theme object include:
You can use [Zed's Theme Builder](https://zed.dev/theme-builder) to design your own custom theme based on an existing one.
-This tool lets you fine-tune and preview how every surface in the Zed app will look.
-You can then export the JSON for more easily publishing it in Zed's extension store.
+This tool lets you fine-tune and preview how surfaces in Zed will look.
+You can then export the JSON and publish it in Zed's extension store.
@@ -5,9 +5,9 @@ description: Get started with Zed, the fast open-source code editor. Essential c
# Getting Started
-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.
+Zed is an open-source code editor with built-in collaboration and AI tools.
-This guide gets you from zero to productive in Zed. You'll learn the essential commands, configure your environment, and find your way around.
+This guide covers the essential commands, environment setup, and navigation basics.
## Quick Start
@@ -77,7 +77,7 @@ You can also enable familiar keybindings:
## 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.
+Zed is open source. Join us on GitHub or in Discord to contribute code, report bugs, or suggest features.
- [Discord](https://discord.com/invite/zedindustries)
- [GitHub Discussions](https://github.com/zed-industries/zed/discussions)
@@ -5,13 +5,13 @@ description: Helix-style keybindings and modal editing in Zed. Selection-first e
# Helix Mode
-_Work in progress! Not all Helix keybindings are implemented yet._
+_Work in progress. Not all Helix keybindings are implemented yet._
Zed's Helix mode is an emulation layer that brings Helix-style keybindings and modal editing to Zed. It builds upon Zed's [Vim mode](./vim.md), so much of the core functionality is shared. Enabling `helix_mode` will also enable `vim_mode`.
For a guide on Vim-related features that are also available in Helix mode, please refer to our [Vim mode documentation](./vim.md).
-To check the current status of Helix mode, or to request a missing Helix feature, checkout out the ["Are we Helix yet?" discussion](https://github.com/zed-industries/zed/discussions/33580).
+To check the current status of Helix mode, or to request a missing Helix feature, see the ["Are we Helix yet?" discussion](https://github.com/zed-industries/zed/discussions/33580).
For a detailed list of Helix's default keybindings, please visit the [official Helix documentation](https://docs.helix-editor.com/keymap.html).
@@ -1,3 +1,8 @@
+---
+title: Icon Themes
+description: "Zed comes with a built-in icon theme, with more icon themes available as extensions."
+---
+
# Icon Themes
Zed comes with a built-in icon theme, with more icon themes available as extensions.
@@ -203,7 +203,7 @@ If you are defining shortcuts in your personal keymap, you can opt into the key
Since v0.196.0, on Linux, if the key that you type doesn't produce an ASCII character, then we use the QWERTY-layout equivalent key for keyboard shortcuts. This means that many shortcuts can be typed on many layouts.
-We do not yet move shortcuts around to ensure that all the built-in shortcuts can be typed on every layout, so if there are some ASCII characters that cannot be typed, and your keyboard layout has different ASCII characters on the same keys as would be needed to type them, you may need to add custom key bindings to make this work. We do intend to fix this at some point, and help is very much appreciated!
+We do not yet remap shortcuts so every built-in shortcut is typeable on every layout. If your layout cannot type some ASCII characters, you may need custom key bindings. We plan to improve this.
## Tips and tricks
@@ -1,3 +1,8 @@
+---
+title: Language Support
+description: "Overview of programming language support in Zed, including built-in and extension-based languages."
+---
+
# Language Support in Zed
Zed supports hundreds of programming languages and text formats.
@@ -1,3 +1,8 @@
+---
+title: Ansible
+description: "Configure Ansible language support in Zed, including language servers, formatting, and debugging."
+---
+
# Ansible
Support for Ansible in Zed is provided via a community-maintained [Ansible extension](https://github.com/kartikvashistha/zed-ansible).
@@ -1,3 +1,8 @@
+---
+title: AsciiDoc
+description: "Configure AsciiDoc language support in Zed, including language servers, formatting, and debugging."
+---
+
# AsciiDoc
AsciiDoc language support in Zed is provided by the community-maintained [AsciiDoc extension](https://github.com/andreicek/zed-asciidoc).
@@ -1,3 +1,8 @@
+---
+title: Astro
+description: "Configure Astro language support in Zed, including language servers, formatting, and debugging."
+---
+
# Astro
Astro support is available through the [Astro extension](https://github.com/zed-extensions/astro).
@@ -1,3 +1,8 @@
+---
+title: Bash
+description: "Configure Bash language support in Zed, including language servers, formatting, and debugging."
+---
+
# Bash
Bash language support in Zed is provided by the community-maintained [Basher extension](https://github.com/d1y/bash.zed).
@@ -1,3 +1,8 @@
+---
+title: Biome
+description: "Configure Biome language support in Zed, including language servers, formatting, and debugging."
+---
+
# Biome
[Biome](https://biomejs.dev/) support in Zed is provided by the community-maintained [Biome extension](https://github.com/biomejs/biome-zed).
@@ -1,3 +1,8 @@
+---
+title: C
+description: "Configure C language support in Zed, including language servers, formatting, and debugging."
+---
+
# C
C support is available natively in Zed.
@@ -40,7 +45,9 @@ IndentWidth: 2
See [Clang-Format Style Options](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) for a complete list of options.
-You can trigger formatting via {#kb editor::Format} or the `editor: format` action from the command palette or by adding `format_on_save` to your Zed settings:
+You can trigger formatting via {#kb editor::Format} or the `editor: format` action from the command palette or by enabling format on save.
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > C, or add to your settings file:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: Clojure
+description: "Configure Clojure language support in Zed, including language servers, formatting, and debugging."
+---
+
# Clojure
Clojure support is available through the [Clojure extension](https://github.com/zed-extensions/clojure).
@@ -1,3 +1,8 @@
+---
+title: C++
+description: "Configure C++ language support in Zed, including language servers, formatting, and debugging."
+---
+
# C++
C++ support is available natively in Zed.
@@ -92,7 +97,9 @@ PointerAlignment: Left
See [Clang-Format Style Options](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) for a complete list of options.
-You can trigger formatting via {#kb editor::Format} or the `editor: format` action from the command palette or by adding `format_on_save` to your Zed settings:
+You can trigger formatting via {#kb editor::Format} or the `editor: format` action from the command palette or by enabling format on save.
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > C++, or add to your settings file:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: C#
+description: "Configure C# language support in Zed, including language servers, formatting, and debugging."
+---
+
# C#
Note language name is "CSharp" for settings not "C#'
@@ -1,3 +1,8 @@
+---
+title: CSS
+description: "Configure CSS language support in Zed, including language servers, formatting, and debugging."
+---
+
# CSS
Zed has built-in support for CSS.
@@ -1,3 +1,8 @@
+---
+title: Dart
+description: "Configure Dart language support in Zed, including language servers, formatting, and debugging."
+---
+
# Dart
Dart support is available through the [Dart extension](https://github.com/zed-extensions/dart).
@@ -1,3 +1,8 @@
+---
+title: Deno
+description: "Configure Deno language support in Zed, including language servers, formatting, and debugging."
+---
+
# Deno
Deno support is available through the [Deno extension](https://github.com/zed-extensions/deno).
@@ -6,7 +11,9 @@ Deno support is available through the [Deno extension](https://github.com/zed-ex
## Deno Configuration
-To use the Deno Language Server with TypeScript and TSX files, you will likely wish to disable the default language servers and enable deno by adding the following to your `settings.json`:
+To use the Deno Language Server with TypeScript and TSX files, you will likely wish to disable the default language servers and enable Deno.
+
+Configure language servers and formatters in Settings ({#kb zed::OpenSettings}) under Languages > JavaScript/TypeScript/TSX, or add to your settings file:
```json [settings]
{
@@ -59,7 +66,7 @@ TBD: Deno TypeScript REPL instructions [docs/repl#typescript-deno](../repl.md#ty
## Configuration completion
-To get completions for `deno.json` or `package.json` you can add the following to your `settings.json`: (More info here https://zed.dev/docs/languages/json)
+To get completions for `deno.json` or `package.json`, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)). For more details, see [JSON](./json.md).
```json [settings]
"lsp": {
@@ -1,3 +1,8 @@
+---
+title: Diff
+description: "Configure Diff language support in Zed, including language servers, formatting, and debugging."
+---
+
# Diff
Diff support is available natively in Zed.
@@ -1,3 +1,8 @@
+---
+title: Docker
+description: "Configure Docker language support in Zed, including language servers, formatting, and debugging."
+---
+
# Docker
Support for `Dockerfile` and `docker-compose.yaml` in Zed is provided by community-maintained extensions.
@@ -1,3 +1,8 @@
+---
+title: Elixir
+description: "Configure Elixir language support in Zed, including language servers, formatting, and debugging."
+---
+
# Elixir
Elixir support is available through the [Elixir extension](https://github.com/zed-extensions/elixir).
@@ -19,7 +24,7 @@ The Elixir extension offers language server support for `expert`, `elixir-ls`, `
### Expert
-To switch to `expert`, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Elixir, or add to your settings file:
```json [settings]
"languages": {
@@ -34,7 +39,7 @@ To switch to `expert`, add the following to your `settings.json`:
### Next LS
-To switch to `next-ls`, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Elixir, or add to your settings file:
```json [settings]
"languages": {
@@ -49,7 +54,7 @@ To switch to `next-ls`, add the following to your `settings.json`:
### Lexical
-To switch to `lexical`, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Elixir, or add to your settings file:
```json [settings]
"languages": {
@@ -82,7 +87,9 @@ brew install elixir-ls
### Formatting with Mix
-If you prefer to format your code with [Mix](https://hexdocs.pm/mix/Mix.html), use the following snippet in your `settings.json` file to configure it as an external formatter. Formatting will occur on file save.
+If you prefer to format your code with [Mix](https://hexdocs.pm/mix/Mix.html), configure it as an external formatter. Formatting will occur on file save.
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Elixir, or add to your settings file:
```json [settings]
{
@@ -102,7 +109,7 @@ If you prefer to format your code with [Mix](https://hexdocs.pm/mix/Mix.html), u
### Additional workspace configuration options
-You can pass additional elixir-ls workspace configuration options via lsp settings in `settings.json`.
+You can pass additional elixir-ls workspace configuration options via `lsp` settings in your settings file ([how to edit](../configuring-zed.md#settings-files)).
The following example disables dialyzer:
@@ -126,7 +133,7 @@ Zed also supports HEEx templates. HEEx is a mix of [EEx](https://hexdocs.pm/eex/
#### Using the Tailwind CSS Language Server with HEEx
-To get all the features (autocomplete, linting, etc.) from the [Tailwind CSS language server](https://github.com/tailwindlabs/tailwindcss-intellisense/tree/HEAD/packages/tailwindcss-language-server#readme) in HEEx files, you need to configure the language server so that it knows about where to look for CSS classes by adding the following to your `settings.json`:
+To get all features (autocomplete, linting, and hover docs) from the [Tailwind CSS language server](https://github.com/tailwindlabs/tailwindcss-intellisense/tree/HEAD/packages/tailwindcss-language-server#readme) in HEEx files, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)):
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: Elm
+description: "Configure Elm language support in Zed, including language servers, formatting, and debugging."
+---
+
# Elm
Elm support is available through the [Elm extension](https://github.com/zed-extensions/elm).
@@ -1,3 +1,8 @@
+---
+title: Emmet
+description: "Configure Emmet language support in Zed, including language servers, formatting, and debugging."
+---
+
# Emmet
Emmet support is available through the [Emmet extension](https://github.com/zed-extensions/emmet).
@@ -1,3 +1,8 @@
+---
+title: Erlang
+description: "Configure Erlang language support in Zed, including language servers, formatting, and debugging."
+---
+
# Erlang
Erlang support is available through the [Erlang extension](https://github.com/zed-extensions/erlang).
@@ -13,7 +18,7 @@ The Erlang extension offers language server support for `erlang_ls` and `erlang-
`erlang_ls` is enabled by default.
-To switch to `erlang-language-platform`, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Erlang, or add to your settings file:
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: Fish
+description: "Configure Fish language support in Zed, including language servers, formatting, and debugging."
+---
+
# Fish
Fish language support in Zed is provided by the community-maintained [Fish extension](https://github.com/hasit/zed-fish).
@@ -1,3 +1,8 @@
+---
+title: GDScript
+description: "Configure GDScript language support in Zed, including language servers, formatting, and debugging."
+---
+
# GDScript
Godot [GDScript](https://gdscript.com/) language support in Zed is provided by the community-maintained [GDScript extension](https://github.com/GDQuest/zed-gdscript).
@@ -1,3 +1,8 @@
+---
+title: Gleam
+description: "Configure Gleam language support in Zed, including language servers, formatting, and debugging."
+---
+
# Gleam
Gleam support is available through the [Gleam extension](https://github.com/gleam-lang/zed-gleam). To learn about Gleam, see the [docs](https://gleam.run/documentation/) or check out the [`stdlib` reference](https://hexdocs.pm/gleam_stdlib/). The Gleam language server has a variety of features, including go-to definition, automatic imports, and [more](https://gleam.run/language-server/).
@@ -1,3 +1,8 @@
+---
+title: GLSL
+description: "Configure GLSL language support in Zed, including language servers, formatting, and debugging."
+---
+
# GLSL
GLSL (OpenGL Shading Language) support is available through the [GLSL Extension](https://github.com/zed-industries/zed/tree/main/extensions/glsl/)
@@ -1,3 +1,8 @@
+---
+title: Go
+description: "Configure Go language support in Zed, including language servers, formatting, and debugging."
+---
+
# Go
Go support is available natively in Zed.
@@ -1,3 +1,8 @@
+---
+title: Groovy
+description: "Configure Groovy language support in Zed, including language servers, formatting, and debugging."
+---
+
# Groovy
Groovy language support in Zed is provided by the community-maintained [Groovy extension](https://github.com/valentinegb/zed-groovy).
@@ -1,3 +1,8 @@
+---
+title: Haskell
+description: "Configure Haskell language support in Zed, including language servers, formatting, and debugging."
+---
+
# Haskell
Haskell support is available through the [Haskell extension](https://github.com/zed-extensions/haskell).
@@ -1,3 +1,8 @@
+---
+title: Helm
+description: "Configure Helm language support in Zed, including language servers, formatting, and debugging."
+---
+
# Helm
Support for Helm in Zed is provided by the community-maintained [Helm extension](https://github.com/cabrinha/helm.zed).
@@ -1,3 +1,8 @@
+---
+title: HTML
+description: "Configure HTML language support in Zed, including language servers, formatting, and debugging."
+---
+
# HTML
HTML support is available through the [HTML extension](https://github.com/zed-industries/zed/tree/main/extensions/html).
@@ -19,7 +24,7 @@ This extension is automatically installed, but if you do not want to use it, you
By default Zed uses [Prettier](https://prettier.io/) for formatting HTML.
-You can disable `format_on_save` by adding the following to your Zed `settings.json`:
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > HTML, or add to your settings file:
```json [settings]
"languages": {
@@ -29,11 +34,11 @@ You can disable `format_on_save` by adding the following to your Zed `settings.j
}
```
-You can still trigger formatting manually with {#kb editor::Format} or by opening [the Command Palette](..//getting-started.md#command-palette) ({#kb command_palette::Toggle}) and selecting "Format Document".
+You can still trigger formatting manually with {#kb editor::Format} or by opening the [command palette](..//getting-started.md#command-palette) ({#kb command_palette::Toggle}) and selecting "Format Document".
### LSP Formatting
-To use the `vscode-html-language-server` language server auto-formatting instead of Prettier, add the following to your Zed settings:
+To use the `vscode-html-language-server` language server auto-formatting instead of Prettier, configure the formatter in Settings ({#kb zed::OpenSettings}) under Languages > HTML, or add to your settings file:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: Java
+description: "Configure Java language support in Zed, including language servers, formatting, and debugging."
+---
+
# Java
Java language support in Zed is provided by:
@@ -1,3 +1,8 @@
+---
+title: JavaScript
+description: "Configure JavaScript language support in Zed, including language servers, formatting, and debugging."
+---
+
# JavaScript
JavaScript support is available natively in Zed.
@@ -14,7 +19,9 @@ But many JavaScript projects use other command-line code-formatting tools, such
You can use one of these tools by specifying an _external_ code formatter for JavaScript in your settings.
See [the configuration docs](../reference/all-settings.md) for more information.
-For example, if you have Prettier installed and on your `PATH`, you can use it to format JavaScript files by adding the following to your `settings.json`:
+For example, if you have Prettier installed and on your `PATH`, you can use it to format JavaScript files.
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > JavaScript, or add to your settings file:
```json [settings]
{
@@ -44,7 +51,9 @@ Zed uses [tree-sitter/tree-sitter-jsdoc](https://github.com/tree-sitter/tree-sit
## ESLint
-You can configure Zed to format code using `eslint --fix` by running the ESLint code action when formatting:
+You can configure Zed to format code using `eslint --fix` by running the ESLint code action when formatting.
+
+Configure code actions on format in Settings ({#kb zed::OpenSettings}) under Languages > JavaScript, or add to your settings file:
```json [settings]
{
@@ -86,8 +95,9 @@ You can also only execute a single ESLint rule when using `fixAll`:
> ESLint's rules, then they will overwrite what ESLint fixed and you end up with
> errors.
-If you **only** want to run ESLint on save, you can configure code actions as
-the formatter:
+If you **only** want to run ESLint on save, you can configure code actions as the formatter.
+
+Configure in Settings ({#kb zed::OpenSettings}) under Languages > JavaScript, or add to your settings file:
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: JSON
+description: "Configure JSON language support in Zed, including language servers, formatting, and debugging."
+---
+
# JSON
JSON support is available natively in Zed.
@@ -1,3 +1,8 @@
+---
+title: Jsonnet
+description: "Configure Jsonnet language support in Zed, including language servers, formatting, and debugging."
+---
+
# Jsonnet
Jsonnet language support in Zed is provided by the community-maintained [Jsonnet extension](https://github.com/narqo/zed-jsonnet).
@@ -9,7 +14,7 @@ Jsonnet language support in Zed is provided by the community-maintained [Jsonnet
Workspace configuration options can be passed to the language server via the `lsp` settings of the `settings.json`.
-The following example enables support for resolving [tanka](https://tanka.dev) import paths in `jsonnet-language-server`:
+The following example configures `jsonnet-language-server` to resolve [tanka](https://tanka.dev) import paths:
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: Julia
+description: "Configure Julia language support in Zed, including language servers, formatting, and debugging."
+---
+
# Julia
Julia language support in Zed is provided by the community-maintained [Julia extension](https://github.com/JuliaEditorSupport/zed-julia).
@@ -1,3 +1,8 @@
+---
+title: Kotlin
+description: "Configure Kotlin language support in Zed, including language servers, formatting, and debugging."
+---
+
# Kotlin
Kotlin language support in Zed is provided by the community-maintained [Kotlin extension](https://github.com/zed-extensions/kotlin).
@@ -1,3 +1,8 @@
+---
+title: Lua
+description: "Configure Lua language support in Zed, including language servers, formatting, and debugging."
+---
+
# Lua
Lua support is available through the [Lua extension](https://github.com/zed-extensions/lua).
@@ -7,7 +12,7 @@ Lua support is available through the [Lua extension](https://github.com/zed-exte
## luarc.json
-To configure LuaLS you can create a `.luarc.json` file in the root of your workspace.
+To configure LuaLS you can create a `.luarc.json` file in the root of your project.
```json [settings]
{
@@ -88,7 +93,7 @@ Then in your `.luarc.json`:
To enable [Inlay Hints](../configuring-languages.md#inlay-hints) for LuaLS in Zed
-1. Add the following to your Zed settings.json:
+1. Configure inlay hints in Settings ({#kb zed::OpenSettings}) under Languages > Lua, or add to your settings file:
```json [settings]
"languages": {
@@ -118,7 +123,7 @@ To enable auto-formatting with your LuaLS (provided by [CppCXY/EmmyLuaCodeStyle]
}
```
-Then add the following to your Zed `settings.json`:
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Lua, or add to your settings file:
```json [settings]
{
@@ -138,7 +143,7 @@ You can customize various EmmyLuaCodeStyle style options via `.editorconfig`, se
Alternatively to use [StyLua](https://github.com/JohnnyMorganz/StyLua) for auto-formatting:
1. Install [StyLua](https://github.com/JohnnyMorganz/StyLua): `brew install stylua` or `cargo install stylua --features lua52,lua53,lua54,luau,luajit` (feel free to remove any Lua versions you don't need).
-2. Add the following to your `settings.json`:
+2. Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Lua, or add to your settings file:
```json [settings]
{
@@ -162,7 +167,7 @@ Alternatively to use [StyLua](https://github.com/JohnnyMorganz/StyLua) for auto-
}
```
-You can specify various options to StyLua either on the command line above (like `--syntax=Lua54`) or in a `stylua.toml` in your workspace:
+You can specify various options to StyLua either on the command line above (like `--syntax=Lua54`) or in a `stylua.toml` in your project:
```toml
syntax = "Lua54"
@@ -1,3 +1,8 @@
+---
+title: Luau
+description: "Configure Luau language support in Zed, including language servers, formatting, and debugging."
+---
+
# Luau
[Luau](https://luau.org/) is a fast, small, safe, gradually typed, embeddable scripting language derived from Lua. Luau was developed by Roblox and is available under the MIT license.
@@ -25,7 +30,7 @@ brew install stylua
cargo install stylua --features lua52,lua53,lua54,luau
```
-Then add the following to your Zed `settings.json`:
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Luau, or add to your settings file:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: Makefile
+description: "Configure Makefile language support in Zed, including language servers, formatting, and debugging."
+---
+
# Makefile
Makefile language support in Zed is provided by the community-maintained [Make extension](https://github.com/caius/zed-make).
@@ -1,3 +1,8 @@
+---
+title: Markdown
+description: "Configure Markdown language support in Zed, including language servers, formatting, and debugging."
+---
+
# Markdown
Markdown support is available natively in Zed.
@@ -23,7 +28,9 @@ def fib(n):
### Format
-Zed supports using Prettier to automatically re-format Markdown documents. You can trigger this manually via the {#action editor::Format} action or via the {#kb editor::Format} keyboard shortcut. Alternately, you can automatically format by enabling [`format_on_save`](../reference/all-settings.md#format-on-save) in your settings.json:
+Zed supports using Prettier to automatically re-format Markdown documents. You can trigger this manually via the {#action editor::Format} action or via the {#kb editor::Format} keyboard shortcut. Alternately, you can enable format on save.
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Markdown, or add to your settings file:
```json [settings]
"languages": {
@@ -43,7 +50,7 @@ Zed automatically continues lists when you press Enter at the end of a list item
Pressing Enter on an empty list item removes the marker and exits the list.
-To disable this behavior:
+To disable this behavior, configure in Settings ({#kb zed::OpenSettings}) under Languages > Markdown, or add to your settings file:
```json [settings]
"languages": {
@@ -57,7 +64,7 @@ To disable this behavior:
Zed indents list items when you press Tab while the cursor is on a line containing only a list marker. This allows you to quickly create nested lists.
-To disable this behavior:
+To disable this behavior, configure in Settings ({#kb zed::OpenSettings}) under Languages > Markdown, or add to your settings file:
```json [settings]
"languages": {
@@ -69,7 +76,9 @@ To disable this behavior:
### Trailing Whitespace
-By default Zed will remove trailing whitespace on save. If you rely on invisible trailing whitespace being converted to `<br />` in Markdown files you can disable this behavior with:
+By default Zed will remove trailing whitespace on save. If you rely on invisible trailing whitespace being converted to `<br />` in Markdown files you can disable this behavior.
+
+Configure in Settings ({#kb zed::OpenSettings}) under Languages > Markdown, or add to your settings file:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: Nim
+description: "Configure Nim language support in Zed, including language servers, formatting, and debugging."
+---
+
# Nim
Nim language support in Zed is provided by the community-maintained [Nim extension](https://github.com/foxoman/zed-nim).
@@ -8,7 +13,9 @@ Report issues to: [https://github.com/foxoman/zed-nim/issues](https://github.com
## Formatting
-To use [arnetheduck/nph](https://github.com/arnetheduck/nph) as a formatter, follow the [nph installation instructions](https://github.com/arnetheduck/nph?tab=readme-ov-file#installation) and add this to your Zed `settings.json`:
+To use [arnetheduck/nph](https://github.com/arnetheduck/nph) as a formatter, follow the [nph installation instructions](https://github.com/arnetheduck/nph?tab=readme-ov-file#installation).
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Nim, or add to your settings file:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: OCaml
+description: "Configure OCaml language support in Zed, including language servers, formatting, and debugging."
+---
+
# OCaml
OCaml support is available through the [OCaml extension](https://github.com/zed-extensions/ocaml).
@@ -33,4 +38,4 @@ Once you have the cli, simply from a terminal, navigate to your project and run
zed .
```
-VoilĂ ! You should have Zed running with OCaml support, no additional setup required.
+You should now have Zed running with OCaml support, with no additional setup required.
@@ -1,3 +1,8 @@
+---
+title: OpenTofu
+description: "Configure OpenTofu language support in Zed, including language servers, formatting, and debugging."
+---
+
# OpenTofu
OpenTofu support is available through the [OpenTofu extension](https://github.com/ashpool37/zed-extension-opentofu).
@@ -7,7 +12,7 @@ OpenTofu support is available through the [OpenTofu extension](https://github.co
## Configuration
-In order to automatically use the OpenTofu extension and language server when editing .tf and .tfvars files,
+To automatically use the OpenTofu extension and language server when editing `.tf` and `.tfvars` files,
either uninstall the Terraform extension or add this to your settings.json:
```json
@@ -1,3 +1,8 @@
+---
+title: PHP
+description: "Configure PHP language support in Zed, including language servers, formatting, and debugging."
+---
+
# PHP
PHP support is available through the [PHP extension](https://github.com/zed-extensions/php).
@@ -39,7 +44,7 @@ The PHP extension uses [LSP language servers](https://microsoft.github.io/langua
[Intelephense](https://intelephense.com/) is a [proprietary](https://github.com/bmewburn/vscode-intelephense/blob/master/LICENSE.txt#L29) language server for PHP operating under a freemium model. Certain features require purchase of a [premium license](https://intelephense.com/buy).
-To use Intelephense, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > PHP, or add to your settings file:
```json [settings]
{
@@ -71,7 +76,7 @@ Alternatively, you can pass the licence key or a path to a file containing the l
[PHP Tools](https://www.devsense.com/) is a proprietary language server that offers free and premium features. You need to [purchase a license](https://www.devsense.com/en/purchase) to activate the premium features.
-To use PHP Tools, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > PHP, or add to your settings file:
```json [settings]
{
@@ -107,7 +112,7 @@ Check out the documentation of [PHP Tools for Zed](https://docs.devsense.com/oth
### Phpactor
-To use Phpactor instead of Intelephense or any other tools, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > PHP, or add to your settings file:
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: PowerShell
+description: "Configure PowerShell language support in Zed, including language servers, formatting, and debugging."
+---
+
# PowerShell
PowerShell language support in Zed is provided by the community-maintained [Zed PowerShell extension](https://github.com/wingyplus/zed-powershell). Please report issues to: [github.com/wingyplus/zed-powershell/issues](https://github.com/wingyplus/zed-powershell/issues)
@@ -1,3 +1,8 @@
+---
+title: Prisma
+description: "Configure Prisma language support in Zed, including language servers, formatting, and debugging."
+---
+
# Prisma
Prisma support is available through the [Prisma extension](https://github.com/zed-extensions/prisma).
@@ -1,3 +1,8 @@
+---
+title: Proto
+description: "Configure Proto language support in Zed, including language servers, formatting, and debugging."
+---
+
# Proto
Proto/proto3 (Protocol Buffers definition language) support is available through the [Proto extension](https://github.com/zed-industries/zed/tree/main/extensions/proto).
@@ -1,3 +1,8 @@
+---
+title: PureScript
+description: "Configure PureScript language support in Zed, including language servers, formatting, and debugging."
+---
+
# PureScript
PureScript support is available through the [PureScript extension](https://github.com/zed-extensions/purescript).
@@ -1,3 +1,8 @@
+---
+title: Python
+description: "Configure Python language support in Zed, including language servers, formatting, and debugging."
+---
+
# How to Set Up Python in Zed
Python support is available natively in Zed.
@@ -75,7 +80,9 @@ Other built-in language servers are:
- [Pyright](https://github.com/microsoft/pyright)—The basis for basedpyright.
- [PyLSP](https://github.com/python-lsp/python-lsp-server)—A plugin-based language server that integrates with tools like `pycodestyle`, `autopep8`, and `yapf`.
-These are disabled by default, but can be enabled in your settings. For example:
+These are disabled by default, but can be enabled in your settings.
+
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Python, or add to your settings file:
```json [settings]
{
@@ -116,7 +123,7 @@ Examples of both kinds of configuration are provided below. Refer to the basedpy
Language server settings for basedpyright in Zed can be set in the `lsp` section of your `settings.json`.
-For example, in order to:
+For example, to:
- diagnose all files in the workspace instead of the only open files default
- disable inlay hints on function arguments
@@ -194,7 +201,9 @@ Zed uses [Ruff](https://github.com/astral-sh/ruff) for formatting and linting Py
### Configuring Formatting
-Formatting in Zed follows a two-phase pipeline: first, code actions on format (`code_actions_on_format`) are executed, followed by the configured formatter:
+Formatting in Zed follows a two-phase pipeline: first, code actions on format (`code_actions_on_format`) are executed, followed by the configured formatter.
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Python, or add to your settings file:
```json [settings]
{
@@ -213,7 +222,9 @@ Formatting in Zed follows a two-phase pipeline: first, code actions on format (`
}
```
-These two phases are independent. For example, if you prefer [Black](https://github.com/psf/black) for code formatting, but want to keep Ruff's import sorting, you only need to change the formatter phase:
+These two phases are independent. For example, if you prefer [Black](https://github.com/psf/black) for code formatting, but want to keep Ruff's import sorting, you only need to change the formatter phase.
+
+Configure in Settings ({#kb zed::OpenSettings}) under Languages > Python, or add to your settings file:
```json [settings]
{
@@ -237,7 +248,9 @@ These two phases are independent. For example, if you prefer [Black](https://git
To completely switch to another tool and prevent Ruff from modifying your code at all, you must explicitly set `source.organizeImports.ruff` to false in the `code_actions_on_format` section, in addition to changing the formatter.
-To prevent any formatting actions when you save, you can disable format-on-save for Python files in your `settings.json`:
+To prevent any formatting actions when you save, you can disable format-on-save for Python files.
+
+Configure in Settings ({#kb zed::OpenSettings}) under Languages > Python, or add to your settings file:
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: R
+description: "Configure R language support in Zed, including language servers, formatting, and debugging."
+---
+
# R
R support is available via multiple R Zed extensions:
@@ -56,7 +61,7 @@ See [Using lintr](https://lintr.r-lib.org/articles/lintr.html) for a complete li
Ensure that you have installed both the [ocsmit/zed-r](https://github.com/ocsmit/zed-r) extension (for general R language awareness in Zed) and the [Air](https://posit-dev.github.io/air/) extension.
-Enable Air in your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > R, or add to your settings file:
```json [settings]
{
@@ -68,7 +73,7 @@ Enable Air in your `settings.json`:
}
```
-If you use the `"r_language_server"` from `REditorSupport/languageserver`, but would still like to use Air for formatting, use the following configuration:
+If you use the `"r_language_server"` from `REditorSupport/languageserver`, but would still like to use Air for formatting, configure in Settings ({#kb zed::OpenSettings}) under Languages > R, or add to your settings file:
```json [settings]
{
@@ -87,7 +92,7 @@ Note that `"air"` must come first in this list, otherwise [r-lib/styler](https:/
#### Configuring Air
-Air is minimally configurable via an `air.toml` file placed in the root directory of your project:
+Air is minimally configurable via an `air.toml` file placed in the root folder of your project:
```toml
[format]
@@ -1,3 +1,8 @@
+---
+title: Racket
+description: "Configure Racket language support in Zed, including language servers, formatting, and debugging."
+---
+
# Racket
Racket support is available through the [Racket extension](https://github.com/zed-extensions/racket).
@@ -1,3 +1,8 @@
+---
+title: Rego
+description: "Configure Rego language support in Zed, including language servers, formatting, and debugging."
+---
+
# Rego
Rego language support in Zed is provided by the community-maintained [Rego extension](https://github.com/StyraInc/zed-rego).
@@ -1,3 +1,8 @@
+---
+title: Roc
+description: "Configure Roc language support in Zed, including language servers, formatting, and debugging."
+---
+
# Roc
[Roc](https://www.roc-lang.org/) is a fast, friendly, functional language.
@@ -1,3 +1,8 @@
+---
+title: reStructuredText
+description: "Configure reStructuredText language support in Zed, including language servers, formatting, and debugging."
+---
+
# ReStructuredText (rst)
ReStructuredText language support in Zed is provided by the community-maintained [reST extension](https://github.com/elmarco/zed-rst).
@@ -1,3 +1,8 @@
+---
+title: Ruby
+description: "Configure Ruby language support in Zed, including language servers, formatting, and debugging."
+---
+
# Ruby
Ruby support is available through the [Ruby extension](https://github.com/zed-extensions/ruby).
@@ -27,7 +32,7 @@ In addition to these two language servers, Zed also supports:
- [rubocop](https://github.com/rubocop/rubocop) which is a static code analyzer and linter for Ruby. Under the hood, it's also used by Zed as a language server, but its functionality is complimentary to that of solargraph and ruby-lsp.
- [sorbet](https://sorbet.org/) which is a static type checker for Ruby with a custom gradual type system.
-- [steep](https://github.com/soutaro/steep) which is a static type checker for Ruby that leverages Ruby Signature (RBS).
+- [steep](https://github.com/soutaro/steep) which is a static type checker for Ruby that uses Ruby Signature (RBS).
- [Herb](https://herb-tools.dev) which is a language server for ERB files.
When configuring a language server, it helps to open the LSP Logs window using the 'dev: Open Language Server Logs' command. You can then choose the corresponding language instance to see any logged information.
@@ -64,7 +69,7 @@ You can skip step 1 and force using the system executable by setting `use_bundle
### Using `ruby-lsp`
-To switch to `ruby-lsp`, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Ruby, or add to your settings file:
```json [settings]
{
@@ -88,13 +93,13 @@ To switch to `ruby-lsp`, add the following to your `settings.json`:
}
```
-That disables `solargraph` and `rubocop` and enables `ruby-lsp`.
+That disables `solargraph` and `rubocop` and uses `ruby-lsp`.
### Using `rubocop`
The Ruby extension also provides support for `rubocop` language server for offense detection and autocorrection.
-To enable it, add the following to your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Ruby, or add to your settings file:
```json [settings]
{
@@ -106,7 +111,7 @@ To enable it, add the following to your `settings.json`:
}
```
-Or, conversely, you can disable `ruby-lsp` and enable `solargraph` and `rubocop` by adding the following to your `settings.json`:
+Or, conversely, you can disable `ruby-lsp` and enable `solargraph` and `rubocop`:
```json [settings]
{
@@ -212,7 +217,9 @@ Rubocop has unsafe autocorrection disabled by default. We can tell Zed to enable
[Sorbet](https://sorbet.org/) is a popular static type checker for Ruby that includes a language server.
-To enable Sorbet, add `\"sorbet\"` to the `language_servers` list for Ruby in your `settings.json`. You may want to disable other language servers if Sorbet is intended to be your primary LSP, or if you plan to use it alongside another LSP for specific features like type checking.
+To enable Sorbet, add `\"sorbet\"` to the `language_servers` list for Ruby. You may want to disable other language servers if Sorbet is intended to be your primary LSP, or if you plan to use it alongside another LSP for specific features like type checking.
+
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Ruby, or add to your settings file:
```json [settings]
{
@@ -236,7 +243,9 @@ For all aspects of installing Sorbet, setting it up in your project, and configu
[Steep](https://github.com/soutaro/steep) is a static type checker for Ruby that uses RBS files to define types.
-To enable Steep, add `\"steep\"` to the `language_servers` list for Ruby in your `settings.json`. You may need to adjust the order or disable other LSPs depending on your desired setup.
+To enable Steep, add `\"steep\"` to the `language_servers` list for Ruby. You may need to adjust the order or disable other LSPs depending on your desired setup.
+
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > Ruby, or add to your settings file:
```json [settings]
{
@@ -397,6 +406,8 @@ The Ruby extension provides a debug adapter for debugging Ruby code. Zed's name
To format ERB templates, you can use the `erb-formatter` formatter. This formatter uses the [`erb-formatter`](https://rubygems.org/gems/erb-formatter) gem to format ERB templates.
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > HTML+ERB, or add to your settings file:
+
```json [settings]
{
"HTML+ERB": {
@@ -1,3 +1,8 @@
+---
+title: Rust
+description: "Configure Rust language support in Zed, including language servers, formatting, and debugging."
+---
+
# Rust
Rust support is available natively in Zed.
@@ -7,7 +12,7 @@ Rust support is available natively in Zed.
- Debug Adapter: [CodeLLDB](https://github.com/vadimcn/codelldb) (primary), [GDB](https://sourceware.org/gdb/) (secondary, not available on Apple silicon)
<!--
-TBD: Polish Rust Docs. Zed is a good rust editor, good Rust docs make it look like we care about Rust (we do!)
+TBD: Polish Rust docs. Zed has strong Rust support, and the docs should reflect that clearly.
TBD: Users may not know what inlayHints, don't start there.
TBD: Provide explicit examples not just `....`
-->
@@ -1,3 +1,8 @@
+---
+title: Scala
+description: "Configure Scala language support in Zed, including language servers, formatting, and debugging."
+---
+
# Scala
Scala language support in Zed is provided by the community-maintained [Scala extension](https://github.com/scalameta/metals-zed).
@@ -1,3 +1,8 @@
+---
+title: Scheme
+description: "Configure Scheme language support in Zed, including language servers, formatting, and debugging."
+---
+
# Scheme
Scheme support is available through the [Scheme extension](https://github.com/zed-extensions/scheme).
@@ -1,3 +1,8 @@
+---
+title: Shell Script
+description: "Configure Shell Script language support in Zed, including language servers, formatting, and debugging."
+---
+
# Shell Scripts
Shell Scripts (bash, zsh, dash, sh) are supported natively by Zed.
@@ -6,7 +11,7 @@ Shell Scripts (bash, zsh, dash, sh) are supported natively by Zed.
## Settings
-You can configure various settings for Shell Scripts in your Zed User Settings (`~/.config/zed/settings.json`) or Zed Project Settings (`.zed/settings.json`):
+Configure settings in Settings ({#kb zed::OpenSettings}) under Languages > Shell Script, or add to your settings file:
```json [settings]
"languages": {
@@ -39,7 +44,7 @@ which shfmt
shfmt --version
```
-3. Configure Zed to automatically format Shell Scripts with `shfmt` on save:
+3. Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Shell Script, or add to your settings file:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: SQL
+description: "Configure SQL language support in Zed, including language servers, formatting, and debugging."
+---
+
# SQL
SQL files are handled by the [SQL Extension](https://github.com/zed-extensions/sql).
@@ -21,7 +26,7 @@ which sql-formatter
sql-formatter --version
```
-3. Configure Zed to automatically format SQL with `sql-formatter`:
+3. Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > SQL, or add to your settings file:
```json [settings]
"languages": {
@@ -53,7 +58,7 @@ Sql-formatter also allows more precise control by providing [sql-formatter confi
}
```
-When using a `.sql-formatter.json` file you can use a more simplified set of Zed settings since the language need not be specified inline:
+When using a `.sql-formatter.json` file you can use a simplified Zed settings configuration:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: Svelte
+description: "Configure Svelte language support in Zed, including language servers, formatting, and debugging."
+---
+
# Svelte
Svelte support is available through the [Svelte extension](https://github.com/zed-extensions/svelte).
@@ -1,3 +1,8 @@
+---
+title: Swift
+description: "Configure Swift language support in Zed, including language servers, formatting, and debugging."
+---
+
# Swift
Swift language support in Zed is provided by the community-maintained [Swift extension](https://github.com/zed-extensions/swift).
@@ -1,3 +1,8 @@
+---
+title: Tailwind CSS
+description: "Configure Tailwind CSS language support in Zed, including language servers, formatting, and debugging."
+---
+
# Tailwind CSS
Zed has built-in support for Tailwind CSS autocomplete, linting, and hover previews.
@@ -42,7 +47,7 @@ Refer to [the Tailwind CSS language server settings docs](https://github.com/tai
### Using Tailwind CSS Mode in CSS Files
Zed includes support for the Tailwind CSS language mode, which provides full CSS IntelliSense support even when using Tailwind-specific at-rules like `@apply`, `@layer`, and `@theme`.
-To use the Tailwind CSS language mode for CSS files, add the following to `languages` section of your `settings.json`:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > CSS, or add to your settings file:
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: Terraform
+description: "Configure Terraform language support in Zed, including language servers, formatting, and debugging."
+---
+
# Terraform
Terraform support is available through the [Terraform extension](https://github.com/zed-extensions/terraform).
@@ -1,3 +1,8 @@
+---
+title: TOML
+description: "Configure TOML language support in Zed, including language servers, formatting, and debugging."
+---
+
# TOML
TOML support is available through the [TOML extension](https://zed.dev/extensions/toml).
@@ -1,3 +1,8 @@
+---
+title: TypeScript
+description: "Configure TypeScript language support in Zed, including language servers, formatting, and debugging."
+---
+
# TypeScript
TypeScript and TSX support are available natively in Zed.
@@ -14,7 +19,7 @@ TBD: Document the difference between Language servers
## Language servers
By default Zed uses [vtsls](https://github.com/yioneko/vtsls) for TypeScript, TSX, and JavaScript files.
-You can configure the use of [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server) per language in your settings file:
+Configure language servers in Settings ({#kb zed::OpenSettings}) under Languages > TypeScript/TSX/JavaScript, or add to your settings file:
```json [settings]
{
@@ -32,7 +37,7 @@ You can configure the use of [typescript-language-server](https://github.com/typ
}
```
-Prettier will also be used for TypeScript files by default. To disable this:
+Prettier will also be used for TypeScript files by default. To disable this, configure in Settings ({#kb zed::OpenSettings}) under Languages > TypeScript, or add to your settings file:
```json [settings]
{
@@ -1,3 +1,8 @@
+---
+title: Uiua
+description: "Configure Uiua language support in Zed, including language servers, formatting, and debugging."
+---
+
# Uiua
[Uiua](https://www.uiua.org/) is a general purpose, stack-based, array-oriented programming language with a focus on simplicity, beauty, and tacit code.
@@ -1,3 +1,8 @@
+---
+title: Vue
+description: "Configure Vue language support in Zed, including language servers, formatting, and debugging."
+---
+
# Vue
Vue support is available through the [Vue extension](https://github.com/zed-extensions/vue).
@@ -1,3 +1,8 @@
+---
+title: XML
+description: "Configure XML language support in Zed, including language servers, formatting, and debugging."
+---
+
# XML
XML support is available through the [XML extension](https://github.com/sweetppro/zed-xml/).
@@ -1,3 +1,8 @@
+---
+title: YAML
+description: "Configure YAML language support in Zed, including language servers, formatting, and debugging."
+---
+
# YAML
YAML support is available natively in Zed.
@@ -53,7 +58,7 @@ You can customize the formatting behavior of Prettier. For example to use single
### yaml-language-server Formatting
-To use `yaml-language-server` instead of Prettier for YAML formatting, add the following to your Zed `settings.json`:
+To use `yaml-language-server` instead of Prettier for YAML formatting, configure in Settings ({#kb zed::OpenSettings}) under Languages > YAML, or add to your settings file:
```json [settings]
"languages": {
@@ -1,3 +1,8 @@
+---
+title: Yara
+description: "Configure Yara language support in Zed, including language servers, formatting, and debugging."
+---
+
# Yara
`Yara` language support in Zed is provided by the [Yara language extension](https://github.com/egibs/yara.zed). Please report issues to [https://github.com/egibs/yara.zed/issues](https://github.com/egibs/yara.zed/issues).
@@ -1,9 +1,15 @@
+---
+title: Yarn
+description: "Configure Yarn language support in Zed, including language servers, formatting, and debugging."
+---
+
# Yarn
-[Yarn](https://yarnpkg.com/) is a versatile package manager that improves dependency management and workflow efficiency for JavaScript and other languages. It ensures a deterministic dependency tree, offers offline support, and enhances security for reliable builds.
+[Yarn](https://yarnpkg.com/) is a JavaScript package manager that provides deterministic dependency resolution and offline caching.
## Setup
1. Run `yarn dlx @yarnpkg/sdks base` to generate a `.yarn/sdks` directory.
-2. Set your language server (e.g. VTSLS) to use TypeScript SDK from `.yarn/sdks/typescript/lib` directory in [LSP initialization options](../reference/all-settings.md#lsp). The actual setting for that depends on language server; for example, for VTSLS you should set [`typescript.tsdk`](https://github.com/yioneko/vtsls/blob/6adfb5d3889ad4b82c5e238446b27ae3ee1e3767/packages/service/configuration.schema.json#L5).
-3. Voilla! Language server functionalities such as Go to Definition, Code Completions and On Hover documentation should work.
+2. Set your language server (e.g. VTSLS) to use TypeScript SDK from `.yarn/sdks/typescript/lib` directory in [LSP initialization options](../reference/all-settings.md#lsp). The actual setting depends on your language server; for example, for VTSLS set [`typescript.tsdk`](https://github.com/yioneko/vtsls/blob/6adfb5d3889ad4b82c5e238446b27ae3ee1e3767/packages/service/configuration.schema.json#L5).
+
+After configuration, language server features (Go to Definition, completions, hover documentation) should work correctly.
@@ -1,3 +1,8 @@
+---
+title: Zig
+description: "Configure Zig language support in Zed, including language servers, formatting, and debugging."
+---
+
# Zig
Zig support is available through the [Zig extension](https://github.com/zed-extensions/zig).
@@ -1,3 +1,8 @@
+---
+title: Zed on Linux
+description: "The installation script on the download page is the fastest way to install Zed:"
+---
+
# Zed on Linux
## Standard Installation
@@ -1,3 +1,8 @@
+---
+title: Zed on macOS
+description: "Zed is developed primarily on macOS, making it a first-class platform with full feature support."
+---
+
# Zed on macOS
Zed is developed primarily on macOS, making it a first-class platform with full feature support.
@@ -1,3 +1,8 @@
+---
+title: How to Migrate from IntelliJ IDEA to Zed
+description: "Guide for migrating from IntelliJ IDEA to Zed, including settings and keybindings."
+---
+
# How to Migrate from IntelliJ IDEA to Zed
This guide covers how to set up Zed if you're coming from IntelliJ IDEA, including keybindings, settings, and the differences you should expect.
@@ -36,24 +41,11 @@ If you're coming from IntelliJ, the fastest way to feel at home is to use the Je
2. Search for `Base Keymap`
3. Select `JetBrains`
-Or add this directly to your `settings.json`:
-
-```json
-{
- "base_keymap": "JetBrains"
-}
-```
-
This maps familiar shortcuts like `Shift Shift` for Search Everywhere, `Cmd+O` for Go to Class, and `Cmd+Shift+A` for Find Action.
## Set Up Editor Preferences
-You can configure settings manually in the Settings Editor.
-
-To edit your settings:
-
-1. `Cmd+,` to open the Settings Editor.
-2. Run `zed: open settings` in the Command Palette.
+You can configure most settings in the Settings Editor ({#kb zed::OpenSettings}). For advanced settings, run `zed: open settings file` from the Command Palette to edit your settings file directly.
Settings IntelliJ users typically configure first:
@@ -84,7 +76,7 @@ Once inside a project:
- Use `Cmd+Shift+A` or `Shift Shift` to open the Command Palette (like IntelliJ's "Search Everywhere")
- Use `Cmd+O` to search for symbols (like IntelliJ's "Go to Class")
-Open buffers appear as tabs across the top. The sidebar shows your file tree and Git status. Toggle it with `Cmd+1` (just like IntelliJ's Project tool window).
+Open buffers appear as tabs across the top. The Project Panel shows your file tree and Git status. Toggle it with `Cmd+1` (just like IntelliJ's Project tool window).
## Differences in Keybindings
@@ -219,7 +211,7 @@ IntelliJ's value for enterprise Java development comes largely from its framewor
Zed has none of this. The language server sees Java code as Java code, so it doesn't understand that `@Autowired` means something special or that this class is a REST controller.
-Similarly for other ecosystems: no Rails integration, no Django awareness, no Angular/React-specific tooling beyond what the TypeScript language server provides.
+Similarly for other stacks: no Rails integration, no Django awareness, no Angular/React-specific tooling beyond what the TypeScript language server provides.
**How to adapt:**
@@ -263,9 +255,9 @@ The Debug Panel (`Cmd+5`) shows variables, call stack, and breakpoints—similar
### Extensions vs. Plugins
-IntelliJ has a massive plugin ecosystem covering everything from language support to database tools to deployment integrations.
+IntelliJ has a large plugin catalog covering everything from language support to database tools to deployment integrations.
-Zed's extension ecosystem is smaller and more focused:
+Zed's extension catalog is smaller and more focused:
- Language support and syntax highlighting
- Themes
@@ -331,7 +323,7 @@ Here are a few useful tweaks:
"load_direnv": "shell_hook"
```
-**Configure language servers**: For Java development, you may want to configure the Java language server in your settings:
+**Configure language servers** (requires manual JSON editing): For Java development, you may want to configure the Java language server in your settings:
```json
{
@@ -1,3 +1,8 @@
+---
+title: How to Migrate from PyCharm to Zed
+description: "Guide for migrating from PyCharm to Zed, including settings and keybindings."
+---
+
# How to Migrate from PyCharm to Zed
This guide covers how to set up Zed if you're coming from PyCharm, including keybindings, settings, and the differences you should expect.
@@ -36,24 +41,11 @@ If you're coming from PyCharm, the fastest way to feel at home is to use the Jet
2. Search for `Base Keymap`
3. Select `JetBrains`
-Or add this directly to your `settings.json`:
-
-```json
-{
- "base_keymap": "JetBrains"
-}
-```
-
This maps familiar shortcuts like `Shift Shift` for Search Everywhere, `Cmd+O` for Go to Class, and `Cmd+Shift+A` for Find Action.
## Set Up Editor Preferences
-You can configure settings manually in the Settings Editor.
-
-To edit your settings:
-
-1. `Cmd+,` to open the Settings Editor.
-2. Run `zed: open settings` in the Command Palette.
+You can configure most settings in the Settings Editor ({#kb zed::OpenSettings}). For advanced settings, run `zed: open settings file` from the Command Palette to edit your settings file directly.
Settings PyCharm users typically configure first:
@@ -84,7 +76,7 @@ Once inside a project:
- Use `Cmd+Shift+A` or `Shift Shift` to open the Command Palette (like PyCharm's "Search Everywhere")
- Use `Cmd+O` to search for symbols (like PyCharm's "Go to Symbol")
-Open buffers appear as tabs across the top. The sidebar shows your file tree and Git status. Toggle it with `Cmd+1` (just like PyCharm's Project tool window).
+Open buffers appear as tabs across the top. The Project Panel shows your file tree and Git status. Toggle it with `Cmd+1` (just like PyCharm's Project tool window).
## Differences in Keybindings
@@ -145,7 +137,7 @@ Zed also supports key sequences (multi-key shortcuts).
If you've used PyCharm on large projects, you know the wait: "Indexing..." can take anywhere from 30 seconds to several minutes depending on project size and dependencies. PyCharm builds a comprehensive index of your entire codebase to power its code intelligence, and it re-indexes when dependencies change or when you install new packages.
-Zed doesn't index. You open a folder and start working immediately. File search and navigation work instantly regardless of project size. For many PyCharm users, this alone is reason enough to switch—no more waiting, no more "Indexing paused" interruptions.
+Zed doesn't index. You open a folder and start working immediately. File search and navigation stay fast regardless of project size, without waiting through indexing pauses.
PyCharm's index powers features like finding all usages across your entire codebase, understanding class hierarchies, and detecting unused imports project-wide. Zed delegates this work to language servers, which may not analyze as deeply or as broadly.
@@ -321,9 +313,9 @@ The test output appears in the terminal panel. For pytest, use `--tb=short` for
### Extensions vs. Plugins
-PyCharm has a plugin ecosystem covering everything from additional language support to database tools to deployment integrations.
+PyCharm has a large plugin catalog covering everything from additional language support to database tools to deployment integrations.
-Zed's extension ecosystem is smaller and more focused:
+Zed's extension catalog is smaller and more focused:
- Language support and syntax highlighting
- Themes
@@ -399,7 +391,7 @@ Here are a few useful tweaks:
"load_direnv": "shell_hook"
```
-**Customize virtual environment detection:**
+**Customize virtual environment detection** (requires manual JSON editing):
```json
{
@@ -1,3 +1,8 @@
+---
+title: How to Migrate from RustRover to Zed
+description: "Guide for migrating from RustRover to Zed, including settings and keybindings."
+---
+
# How to Migrate from RustRover to Zed
This guide covers how to set up Zed if you're coming from RustRover, including keybindings, settings, and the differences you should expect as a Rust developer.
@@ -36,24 +41,11 @@ If you're coming from RustRover, the fastest way to feel at home is to use the J
2. Search for `Base Keymap`
3. Select `JetBrains`
-Or add this directly to your `settings.json`:
-
-```json
-{
- "base_keymap": "JetBrains"
-}
-```
-
This maps familiar shortcuts like `Shift Shift` for Search Everywhere, `Cmd+O` for Go to Class, and `Cmd+Shift+A` for Find Action.
## Set Up Editor Preferences
-You can configure settings manually in the Settings Editor.
-
-To edit your settings:
-
-1. `Cmd+,` to open the Settings Editor.
-2. Run `zed: open settings` in the Command Palette.
+You can configure most settings in the Settings Editor ({#kb zed::OpenSettings}). For advanced settings, run `zed: open settings file` from the Command Palette to edit your settings file directly.
Settings RustRover users typically configure first:
@@ -96,7 +88,7 @@ Once inside a project:
- Use `Cmd+Shift+A` or `Shift Shift` to open the Command Palette (like RustRover's "Search Everywhere")
- Use `Cmd+O` to search for symbols (like RustRover's "Go to Symbol")
-Open buffers appear as tabs across the top. The sidebar shows your file tree and Git status. Toggle it with `Cmd+1` (just like RustRover's Project tool window).
+Open buffers appear as tabs across the top. The Project Panel shows your file tree and Git status. Toggle it with `Cmd+1` (just like RustRover's Project tool window).
## Differences in Keybindings
@@ -169,7 +161,7 @@ Zed skips the indexing step. You open a folder and start working right away. Sin
### rust-analyzer: Shared Foundation, Different Integration
-Here's what makes the RustRover-to-Zed transition unique: **both editors use rust-analyzer** for Rust language intelligence. This means the core code analysis—completions, go-to-definition, find references, type inference—is fundamentally the same.
+Here's what makes the RustRover-to-Zed transition unique: **both editors use rust-analyzer** for Rust language intelligence. This means the core code analysis (completions, go-to-definition, find references, type inference) is fundamentally the same.
RustRover integrates rust-analyzer into its JetBrains platform, adding a GUI layer, additional refactorings, and its own indexing on top. Zed uses rust-analyzer more directly through the Language Server Protocol (LSP).
@@ -336,9 +328,9 @@ The test output appears in the terminal panel. For more detailed output, use:
### Extensions vs. Plugins
-RustRover has a plugin ecosystem, though it's more limited than other JetBrains IDEs since Rust support is built-in.
+RustRover has a plugin catalog, though it's more limited than other JetBrains IDEs since Rust support is built-in.
-Zed's extension ecosystem is smaller and more focused:
+Zed's extension catalog is smaller and more focused:
- Language support and syntax highlighting
- Themes
@@ -429,7 +421,7 @@ Here are a few useful tweaks for Rust developers:
}
```
-**Configure rust-analyzer settings:**
+**Configure rust-analyzer settings** (requires manual JSON editing):
```json
{
@@ -1,10 +1,13 @@
-# How to Migrate from VS Code to Zed
+---
+title: How to Migrate from VS Code to Zed
+description: "Guide for migrating from VS Code to Zed, including settings and keybindings."
+---
-This guide is for developers who spent serious time in VS Code and want to try Zed without starting from scratch.
+# How to Migrate from VS Code to Zed
-If you’re here, you might be looking for a faster editor. Or something less cluttered. Or you’re curious about built-in collaboration. Whatever brought you here, this guide helps you move over your habits, shortcuts, and settings.
+This guide explains how to move from VS Code to Zed without rebuilding your workflow.
-We’ll cover what to bring, what to change, and what’s different. You can ease in gradually or switch all at once. Either way, you’ll stay productive.
+It covers which settings import automatically, which shortcuts map cleanly, and which behaviors differ so you can adjust quickly.
## Install Zed
@@ -159,18 +162,13 @@ The following VS Code settings are automatically imported when you use **Import
| `chat.agent.enabled` | `agent.enabled` |
| `mcp` | `context_servers` |
-Zed doesn’t import extensions or keybindings, but this is the fastest way to get a familiar feel while trying something new. If you skip that step during setup, you can still import settings manually later via the command palette:
+Zed doesn’t import extensions or keybindings, but this import gets core editor behavior close to your VS Code setup. If you skip that step during setup, you can still import settings manually later via the command palette:
`Cmd+Shift+P → Zed: Import VS Code Settings`
## Set Up Editor Preferences
-You can also configure settings manually in the Settings Editor.
-
-To edit your settings:
-
-1. `Cmd+,` to open the Settings Editor.
-2. Run `zed: open settings` in the Command Palette.
+You can configure most settings in the Settings Editor ({#kb zed::OpenSettings}). For advanced settings, run `zed: open settings file` from the Command Palette to edit your settings file directly.
Here’s how common VS Code settings translate:
| VS Code | Zed | Notes |
@@ -195,12 +193,12 @@ You can also launch Zed from the terminal inside any folder with:
Once inside a project, use `Cmd+P` to jump between files quickly. `Cmd+Shift+P` (`Ctrl+Shift+P` on Linux) opens the command palette for running actions / tasks, toggling settings, or starting a collaboration session.
-Open buffers appear as tabs across the top. The sidebar shows your file tree and Git status. Collapse it with `Cmd+B` for a distraction-free view.
+Open buffers appear as tabs across the top. The Project Panel shows your file tree and Git status. Collapse it with `Cmd+B` for a distraction-free view.
## Differences in Keybindings
-If you chose the VS Code keymap during onboarding, you're likely good to go, and most of your shortcuts should already feel familiar.
-Here’s a quick reference guide for how our keybindings compare to what you’re used to coming from VS Code.
+If you chose the VS Code keymap during onboarding, most shortcuts should already feel familiar.
+Here’s a quick reference for where keybindings match and where they differ.
### Common Shared Keybindings (Zed <> VS Code)
@@ -274,23 +272,23 @@ Open a folder → work inside that folder → no additional workspace layer.
### Navigating in a Project
-In VS Code, the standard entry point is opening a folder. From there, the left-hand sidebar is central to your navigation.
+In VS Code, the standard entry point is opening a folder. From there, the left-hand panel is central to navigation.
Zed takes a different approach:
- You can still open folders, but you don’t need to. Opening a single file or even starting with an empty workspace is valid.
-- The Command Palette (`Cmd+Shift+P`) and File Finder (`Cmd+P`) are your primary navigation tools. The File Finder searches across the entire workspace instantly; files, symbols, commands, even teammates if you're collaborating.
-- Instead of a persistent sidebar, Zed encourages you to:
+- The Command Palette (`Cmd+Shift+P`) and File Finder (`Cmd+P`) are primary navigation tools. The File Finder searches files, symbols, and commands across the workspace.
+- Instead of a persistent panel, Zed encourages you to:
- Fuzzy-find files by name (`Cmd+P`)
- Jump directly to symbols (`Cmd+Shift+O`)
- Use split panes and tabs for context, rather than keeping a large file tree open (though you can do this with the Project Panel if you prefer).
-The UI is intentionally minimal. Panels slide in only when needed, then get out of your way. The focus is on flowing between code instead of managing panes.
+The UI keeps auxiliary panels out of the way so navigation stays centered on code.
### Extensions vs. Marketplace
Zed does not offer as many extensions as VS Code. The available extensions are focused on language support, themes, syntax highlighting, and other core editing enhancements.
-However there are several features that typically require extensions in VS Code which we built directly into Zed:
+Several features that typically require extensions in VS Code are built into Zed:
- Real-time collaboration with voice and cursor sharing (no Live Share required)
- AI coding assistance (no Copilot extension needed)
@@ -299,7 +297,7 @@ However there are several features that typically require extensions in VS Code
- Task runner with JSON config
- Inline diagnostics and code actions via LSP
-You won’t find one-to-one replacements for every VS Code extension, especially if you rely on tools for DevOps, containers, or test runners. Zed's extension ecosystem is still growing, and the catalog is smaller by design.
+You won’t find one-to-one replacements for every VS Code extension, especially if you rely on tools for DevOps, containers, or test runners. Zed's extension catalog is still growing and remains smaller.
### Collaboration in Zed vs. VS Code
@@ -309,13 +307,13 @@ Unlike VS Code, Zed doesn’t require an extension to collaborate. It’s built
- Create a channel and [invite your collaborators](https://zed.dev/docs/collaboration#inviting-a-collaborator) to join.
- [Share your screen or your codebase](https://zed.dev/docs/collaboration#share-a-project) directly.
-Once connected, you’ll see each other's cursors, selections, and edits in real time. Voice chat is included, so you can talk as you work. There’s no need for separate tools or third-party logins. Zed’s collaboration is designed for everything from quick pair programming to longer team sessions.
+Once connected, you’ll see each other's cursors, selections, and edits in real time. Voice chat is included, so you can talk as you work. There’s no need for separate tools or third-party logins.
Learn how [Zed uses Zed](https://zed.dev/blog/zed-is-our-office) to plan work and collaborate.
### Using AI in Zed
-If you’re used to GitHub Copilot in VS Code, you can do the same in Zed. You can also explore other agents through Zed Pro, or bring your own keys and connect without authentication. Zed is designed to enable many options for using AI, including disabling it entirely.
+If you’re used to GitHub Copilot in VS Code, you can do the same in Zed. You can also explore other agents through Zed Pro, or bring your own keys and connect without authentication. You can disable AI features entirely if you prefer.
#### Configuring GitHub Copilot
@@ -1,3 +1,8 @@
+---
+title: How to Migrate from WebStorm to Zed
+description: "Guide for migrating from WebStorm to Zed, including settings and keybindings."
+---
+
# How to Migrate from WebStorm to Zed
This guide covers how to set up Zed if you're coming from WebStorm, including keybindings, settings, and the differences you should expect as a JavaScript/TypeScript developer.
@@ -36,24 +41,11 @@ If you're coming from WebStorm, the fastest way to feel at home is to use the Je
2. Search for `Base Keymap`
3. Select `JetBrains`
-Or add this directly to your `settings.json`:
-
-```json
-{
- "base_keymap": "JetBrains"
-}
-```
-
This maps familiar shortcuts like `Shift Shift` for Search Everywhere, `Cmd+O` for Go to Class, and `Cmd+Shift+A` for Find Action.
## Set Up Editor Preferences
-You can configure settings manually in the Settings Editor.
-
-To edit your settings:
-
-1. `Cmd+,` to open the Settings Editor.
-2. Run `zed: open settings` in the Command Palette.
+You can configure most settings in the Settings Editor ({#kb zed::OpenSettings}). For advanced settings, run `zed: open settings file` from the Command Palette to edit your settings file directly.
Settings WebStorm users typically configure first:
@@ -84,7 +76,7 @@ Once inside a project:
- Use `Cmd+Shift+A` or `Shift Shift` to open the Command Palette (like WebStorm's "Search Everywhere")
- Use `Cmd+O` to search for symbols (like WebStorm's "Go to Symbol")
-Open buffers appear as tabs across the top. The sidebar shows your file tree and Git status. Toggle it with `Cmd+1` (just like WebStorm's Project tool window).
+Open buffers appear as tabs across the top. The Project Panel shows your file tree and Git status. Toggle it with `Cmd+1` (just like WebStorm's Project tool window).
## Differences in Keybindings
@@ -167,7 +159,7 @@ Zed uses the Language Server Protocol (LSP) for code intelligence. For JavaScrip
- **ESLint** — Linting integration
- **Prettier** — Code formatting (built-in)
-The TypeScript LSP experience is mature and robust. You get accurate completions, type checking, go-to-definition, and find-references. The experience is comparable to VS Code, which uses the same underlying TypeScript services.
+The TypeScript LSP experience is well-supported. You get accurate completions, type checking, go-to-definition, and find-references. The experience is comparable to VS Code, which uses the same underlying TypeScript services.
Where you might notice differences:
@@ -320,9 +312,9 @@ The test output appears in the terminal panel. For Jest, use `--verbose` for det
### Extensions vs. Plugins
-WebStorm has a plugin ecosystem covering additional language support, themes, and tool integrations.
+WebStorm has a plugin catalog covering additional language support, themes, and tool integrations.
-Zed's extension ecosystem is smaller and more focused:
+Zed's extension catalog is smaller and more focused:
- Language support and syntax highlighting
- Themes
@@ -394,7 +386,7 @@ Here are a few useful tweaks for JavaScript/TypeScript developers:
"format_on_save": "on"
```
-**Configure Prettier as the default formatter:**
+**Configure Prettier as the default formatter** (requires manual JSON editing):
```json
{
@@ -407,7 +399,7 @@ Here are a few useful tweaks for JavaScript/TypeScript developers:
}
```
-**Enable ESLint code actions:**
+**Enable ESLint code actions** (requires manual JSON editing):
```json
{
@@ -1,3 +1,8 @@
+---
+title: Rough quick CPU profiling (Flamechart)
+description: "Performance profiling and optimization for Zed development."
+---
+
How to use our internal tools to profile and keep Zed fast.
# Rough quick CPU profiling (Flamechart)
@@ -1,3 +1,8 @@
+---
+title: All Settings
+description: "Complete reference for all Zed settings."
+---
+
# All Settings
This is the complete reference for all Zed settings.
@@ -6,7 +11,7 @@ You may also want to change your [theme](../themes.md), configure your [key bind
# Settings
-Find below an extensive run-through of many supported settings by Zed.
+The sections below document supported Zed settings.
## Active Pane Modifiers
@@ -35,7 +40,7 @@ Non-negative `float` values
### Inactive Opacity
-- Description: Opacity of inactive panels. When set to 1.0, the inactive panes have the same opacity as the active one. If set to 0, the inactive panes content will not be visible at all. Values are clamped to the [0.0, 1.0] range.
+- Description: Opacity of inactive panels. When set to 1.0, inactive panes have the same opacity as the active pane. If set to 0, inactive pane content is not visible. Values are clamped to the [0.0, 1.0] range.
- Setting: `inactive_opacity`
- Default: `1.0`
@@ -129,7 +134,7 @@ Note: This setting has no effect in Vim mode, as rewrap is already allowed every
## Auto Indent
-- Description: Whether indentation should be adjusted based on the context whilst typing. This can be specified on a per-language basis.
+- Description: Whether indentation should be adjusted based on context while typing. This can be specified on a per-language basis.
- Setting: `auto_indent`
- Default: `true`
@@ -149,7 +154,7 @@ Note: This setting has no effect in Vim mode, as rewrap is already allowed every
## Auto Install extensions
-- Description: Define extensions to be autoinstalled or never be installed.
+- Description: Define extensions to install automatically or never install.
- Setting: `auto_install_extensions`
- Default: `{ "html": true }`
@@ -239,7 +244,7 @@ Note that a save will be triggered when an unsaved tab is closed, even if this i
## Auto Signature Help
-- Description: Show method signatures in the editor, when inside parentheses
+- Description: Show method signatures in the editor when inside parentheses.
- Setting: `auto_signature_help`
- Default: `false`
@@ -3270,6 +3275,18 @@ Non-negative `integer` values
- Setting: `regex`
- Default: `false`
+### Search On Input
+
+- Description: Whether to search on input in project search.
+- Setting: `search_on_input`
+- Default: `false`
+
+### Search On Input Debounce Ms
+
+- Description: Debounce time in milliseconds for search on input in project search. Set to 0 to disable debouncing.
+- Setting: `search_on_input_debounce_ms`
+- Default: `200`
+
### Center On Match
- Description: Whether to center the cursor on each search match when navigating.
@@ -3282,12 +3299,6 @@ Non-negative `integer` values
- Setting: `search_wrap`
- Default: `true`
-## Center on Match
-
-- Description: If `center_on_match` is enabled, the editor will center the cursor on the current match when searching.
-- Setting: `center_on_match`
-- Default: `false`
-
## Seed Search Query From Cursor
- Description: When to populate a new search's query based on the text under the cursor.
@@ -1,6 +1,11 @@
+---
+title: CLI Reference
+description: "Reference for Zed's command-line interface (CLI), including opening files and directories, integrating with tools, and controlling Zed from scripts."
+---
+
# CLI Reference
-Zed includes a command-line interface (CLI) for opening files and directories, integrating with other tools, and controlling Zed from scripts.
+Use Zed's command-line interface (CLI) to open files and directories, integrate with other tools, and control Zed from scripts.
## Installation
@@ -1 +1,6 @@
+---
+title: Default Key Bindings
+description: "Reference for Zed's default key bindings."
+---
+
# Default Key Bindings
@@ -1,12 +1,15 @@
---
-title: Remote Development - Zed
-description: Edit code on remote servers with Zed. Local UI performance with remote language servers, terminals, and tasks over SSH.
+title: Remote Development in Zed - SSH Workflows
+description: Use remote development in Zed to edit code over SSH with local UI performance, remote terminals, language servers, and tasks.
---
# Remote Development
Remote Development lets you edit code on a remote server while running Zed locally. The UI stays responsive because it runs on your machine, while language servers, tasks, and terminals run on the server.
+For day-to-day workflows, pair remote development with [Tasks](./tasks.md),
+[Terminal](./terminal.md), and [Debugger](./debugger.md).
+
## Overview
Remote development requires two computers, your local machine that runs the Zed UI and the remote server which runs a Zed headless server. The two communicate over SSH, so you will need to be able to SSH from your local machine into the remote server to use this feature.
@@ -177,7 +180,7 @@ When opening a remote project there are three relevant settings locations:
- The server Zed settings (in the same place) on the remote server.
- The project settings (in `.zed/settings.json` or `.editorconfig` of your project)
-Both the local Zed and the server Zed read the project settings, but they are not aware of the other's main `settings.json`.
+Both the local Zed and the server Zed read the project settings, but they are not aware of the other's main settings file.
Which settings file you should use depends on the kind of setting you want to make:
@@ -258,3 +261,13 @@ Note that we deliberately disallow some options (for example `-t` or `-T`) that
## Feedback
Please join the #remoting-feedback channel in the [Zed Discord](https://zed.dev/community-links).
+
+## See also
+
+- [Running & Testing](./running-testing.md): Run tasks, terminal commands, and
+ debugger sessions while you work remotely.
+- [Configuring Zed](./configuring-zed.md): Manage shared and project settings,
+ including `.zed/settings.json`.
+- [Agent Panel](./ai/agent-panel.md): Use AI workflows in remote projects.
+- [Remote Development on zed.dev](https://zed.dev/remote-development): Product
+ overview and release updates.
@@ -7,7 +7,7 @@ description: Run code interactively in Zed with built-in Jupyter kernel support.
## Getting started
-Bring the power of [Jupyter kernels](https://docs.jupyter.org/en/latest/projects/kernels.html) to your editor! The built-in REPL for Zed allows you to run code interactively in your editor similarly to a notebook with your own text files.
+Zed's built-in REPL uses [Jupyter kernels](https://docs.jupyter.org/en/latest/projects/kernels.html) so you can run code interactively in regular editor files.
<figure style="width: 100%; margin: 0; overflow: hidden; border-top-left-radius: 2px; border-top-right-radius: 2px;">
<video loop controls playsinline>
@@ -1,11 +1,12 @@
---
-title: Running and Testing Code - Zed
-description: Run, test, and debug your code without leaving Zed. Tasks, REPL, and debugger integration.
+title: Run and Test Code in Zed
+description: Run and test code in Zed with Terminal, Tasks, REPL, and debugger workflows without leaving the editor.
---
# Running & Testing
-This section covers how to run, test, and debug your code without leaving Zed.
+Use this section to run and test code in Zed, then debug issues without
+leaving the editor.
## What's here
@@ -1,3 +1,8 @@
+---
+title: Tab Switcher
+description: "The Tab Switcher provides a quick way to navigate between open tabs in Zed. It displays a list of your open tabs sorted by recent usage, making it easy to ju..."
+---
+
# Tab Switcher
The Tab Switcher provides a quick way to navigate between open tabs in Zed. It
@@ -1,3 +1,8 @@
+---
+title: Telemetry
+description: "What data Zed collects and how to control telemetry settings."
+---
+
# Telemetry in Zed
Zed collects anonymous telemetry data to help the team understand how people are using the application and to see what sort of issues they are experiencing.
@@ -5,9 +10,7 @@ Zed collects anonymous telemetry data to help the team understand how people are
## Configuring Telemetry Settings
You have full control over what data is sent out by Zed.
-To enable or disable some or all telemetry types, open your `settings.json` file via {#action zed::OpenSettings}({#kb zed::OpenSettings}) from the command palette.
-
-Insert and tweak the following:
+To enable or disable some or all telemetry types, open Settings ({#kb zed::OpenSettings}) and search for "telemetry", or add the following to your settings file:
```json [settings]
"telemetry": {
@@ -1,9 +1,14 @@
+---
+title: Toolchains
+description: "Zed projects offer a dedicated UI for toolchain selection, which lets you pick a set of tools for working with a given language in a current project."
+---
+
# Toolchains
-Zed projects offer a dedicated UI for toolchain selection, which lets you pick a set of tools for working with a given language in a current project.
+Zed projects include a toolchain selector that lets you choose the tools used for a language in the current project.
-Imagine you're working with Python project, which has virtual environments that encapsulate a set of dependencies of your project along with a suitable interpreter to run it with. The language server has to know which virtual environment you're working with, as it uses it to understand your project's code.
-With toolchain selector, you don't need to spend time configuring your language server to point it at the right virtual environment directory—you can just select the right virtual environment (toolchain) from a dropdown.
+For example, in Python projects, virtual environments define dependencies and interpreter paths. Language servers need that environment to analyze your code correctly.
+With the toolchain selector, you can pick the right virtual environment from a dropdown instead of configuring language server paths manually.
You can even select different toolchains for different subprojects within your Zed project. A definition of a subproject is language-specific.
In collaborative scenarios, only the project owner can see and modify an active toolchain.
@@ -12,19 +17,19 @@ In [remote projects](./remote-development.md), you can use the toolchain selecto
## Why do we need toolchains?
-The active toolchain is relevant for launching language servers, which may need it to function properly—it may not be able to resolve dependencies, which in turn may make functionalities like "Go to definition" or "Code completions" unavailable.
+The active toolchain is used when launching language servers. Without the correct toolchain, language servers may fail to resolve dependencies, and features like "Go to Definition" or "Code Completions" may not work.
The active toolchain is also relevant when launching a shell in the terminal panel: some toolchains provide "activation scripts" for shells, which make those toolchains available in the shell environment for your convenience. Zed will run these activation scripts automatically when you create a new terminal.
-This also applies to [tasks](./tasks.md)—Zed tasks behave "as if" you opened a new terminal tab and ran a given task invocation yourself, which in turn means that Zed task execution is affected by the active toolchain and its activation script.
+This also applies to [tasks](./tasks.md). Zed runs tasks as if you opened a new terminal tab and ran the task command yourself, so task execution is also affected by the active toolchain and its activation script.
## Selecting toolchains
-The active toolchain (if there is one) is displayed in the status bar (on the right hand side). Click on it to access the toolchain selector—you can also use an action from a command palette ({#action toolchain::Select}).
+The active toolchain (if there is one) is shown in the status bar on the right. Click it to open the toolchain selector, or run the command palette action ({#action toolchain::Select}).
Zed will automatically infer a set of toolchains to choose from based on the project you're working with. A default will also be selected on your behalf on a best-effort basis when you open a project for the first time.
-The toolchain selection applies to a current subproject, which—depending on the structure of your Zed project—might be your whole project or just a subset of it. For example, if you have a monorepo with multiple subprojects, you might want to select a different toolchain for each subproject.
+Toolchain selection applies to the current subproject, which may be your whole project or just one part of it. In a monorepo, for example, you might choose a different toolchain for each subproject.
## Adding toolchains manually
@@ -1,8 +1,13 @@
+---
+title: Troubleshooting
+description: "Common issues and solutions for Zed on all platforms."
+---
+
# Troubleshooting
This guide covers common troubleshooting techniques for Zed.
Sometimes you'll be able to identify and resolve issues on your own using this information.
-Other times, troubleshooting means gathering the right information—logs, profiles, or reproduction steps—to help us diagnose and fix the problem.
+Other times, troubleshooting means gathering the right information (logs, profiles, or reproduction steps) to help us diagnose and fix the problem.
> **Note**: To open the command palette, use `cmd-shift-p` on macOS or `ctrl-shift-p` on Windows / Linux.
@@ -25,14 +30,14 @@ You'll find the Zed log in the respective location on each operating system:
- Windows: `C:\Users\YOU\AppData\Local\Zed\logs\Zed.log`
- Linux: `~/.local/share/zed/logs/Zed.log` or `$XDG_DATA_HOME`
-> Note: In some cases, it might be useful to monitor the log live, such as when [developing a Zed extension](https://zed.dev/docs/extensions/developing-extensions).
+> **Note:** In some cases, it might be useful to monitor the log live, such as when [developing a Zed extension](https://zed.dev/docs/extensions/developing-extensions).
> Example: `tail -f ~/Library/Logs/Zed/Zed.log`
The log may contain enough context to help you debug the issue yourself, or you may find specific errors that are useful when filing a [GitHub issue](https://github.com/zed-industries/zed/issues/new/choose) or when talking to Zed staff in our [Discord server](https://zed.dev/community-links#forums-and-discussions).
## Performance Issues (Profiling)
-If you're running into performance issues in Zed—such as hitches, hangs, or general unresponsiveness—having a performance profile attached to your issue will help us zero in on what is getting stuck, so we can fix it.
+If you're running into performance issues in Zed (hitches, hangs, or general unresponsiveness), having a performance profile attached to your issue will help us zero in on what is getting stuck.
### macOS
@@ -1,3 +1,8 @@
+---
+title: Uninstall
+description: "This guide covers how to uninstall Zed on different operating systems."
+---
+
# Uninstall
This guide covers how to uninstall Zed on different operating systems.
@@ -1,3 +1,8 @@
+---
+title: Update Zed
+description: "Zed is designed to keep itself up to date automatically. You can always update this behavior in your settings."
+---
+
# Update Zed
Zed is designed to keep itself up to date automatically. You can always update this behavior in your settings.
@@ -79,7 +79,7 @@ The following commands use the language server to help you navigate and refactor
### Tree-sitter
-Tree-sitter is a powerful tool that Zed uses to understand the structure of your code. Zed provides motions that change the current cursor position, and text objects that can be used as the target of actions.
+Tree-sitter is the parser Zed uses to understand the structure of your code. Zed provides motions that change the current cursor position, and text objects that can be used as the target of actions.
| Command | Default Shortcut |
| ------------------------------- | --------------------------- |
@@ -155,7 +155,7 @@ The following commands help you bring up Zed's completion menu, request a sugges
### Supported plugins
-Zed's vim mode includes some features that are usually provided by very popular plugins in the Vim ecosystem:
+Zed's vim mode includes features commonly provided by plugins in the Vim ecosystem:
- You can surround text objects with `ys` (yank surround), change surrounding with `cs`, and delete surrounding with `ds`.
- You can comment and uncomment selections with `gc` in visual mode and `gcc` in normal mode.
@@ -1,6 +1,11 @@
+---
+title: Visual Customization
+description: "Various aspects of Zed's visual layout can be configured in the Settings Editor or settings file."
+---
+
# Visual Customization
-Various aspects of Zed's visual layout can be configured via either the settings window or the `settings.json` file, which you can access via {#action zed::OpenSettings} ({#kb zed::OpenSettings}) and {#action zed::OpenSettingsFile} ({#kb zed::OpenSettingsFile}) respectively.
+Various aspects of Zed's visual layout can be configured in the Settings Editor ({#kb zed::OpenSettings}) or in your settings file ({#kb zed::OpenSettingsFile}).
See [All Settings](./reference/all-settings.md) for additional information and other non-visual settings.
@@ -1,3 +1,8 @@
+---
+title: Zed on Windows
+description: "Get the latest stable builds via the download page. If you want to download our preview build, you can find it on its [releases p..."
+---
+
# Zed on Windows
## Installing Zed
@@ -1,16 +1,21 @@
+---
+title: Zed and trusted worktrees
+description: "Configure which folders Zed trusts for running code and extensions."
+---
+
# Zed and trusted worktrees
A worktree in Zed is either a directory or a single file that Zed opens as a standalone "project".
-Zed opens a worktree every time `zed some/path` is invoked, on drag and dropping a file or directory into Zed, on opening user settings.json, etc.
+Zed opens a worktree each time you run `zed some/path`, drag a file or directory into Zed, or open your user settings file.
Every worktree opened may contain a `.zed/settings.json` file with extra configuration options that may require installing and spawning language servers or MCP servers.
-In order to provide users the opportunity to make their own choices according to their unique threat model and risk tolerance, all worktrees will be started in Restricted mode, which prevents download and execution of any related items from `.zed/settings.json`. Until configured to trust the worktree(s), Zed will not perform any related untrusted actions and will wait for user confirmation. This gives users a chance to review and understand any pre-configured settings, MCP servers, or language servers associated with a project.
+To let users choose based on their own threat model and risk tolerance, all worktrees start in Restricted Mode. Restricted Mode prevents downloading and running related items from `.zed/settings.json`. Until a worktree is trusted, Zed does not run related untrusted actions and waits for user confirmation. This gives users a chance to review project settings, MCP servers, and language servers.
-Note that at this point, Zed trusts the tools it installs itself, hence global entities such as global MCP servers, language servers like prettier and copilot are still in installed and started as usual, independent of worktree trust.
+Zed still trusts tools it installs globally. Global MCP servers and global language servers such as Prettier and Copilot are installed and started as usual, independent of worktree trust.
If a worktree is not trusted, Zed will indicate this with an exclamation mark icon in the title bar. Clicking this icon or using `workspace::ToggleWorktreeSecurity` action will bring up the security modal that allows the user to trust the worktree.
-Trusting any worktree will persist this information between restarts. It's possible to clear all trusted worktrees with `workspace::ClearTrustedWorktrees` command.
+Trusting a worktree persists that decision between restarts. You can clear all trusted worktrees with the `workspace::ClearTrustedWorktrees` command.
This command will restart Zed, to ensure no untrusted settings, language servers or MCP servers persist.
This feature works locally and on SSH and WSL remote hosts. Zed tracks trust information per host in these cases.
@@ -25,7 +30,7 @@ Restricted Mode prevents:
## Configuring broad worktree trust
-By default, Zed won't trust any new worktrees and users will be required to trust each new worktree. Though not recommended, users may elect to trust all worktrees by configuring the following setting:
+By default, Zed does not trust new worktrees. Users must trust each new worktree individually. Though not recommended, users can trust all worktrees with this setting ([how to edit](./configuring-zed.md#settings-files)):
```json [settings]
"session": {
@@ -33,23 +38,23 @@ By default, Zed won't trust any new worktrees and users will be required to trus
}
```
-Note that auto trusted worktrees are not persisted between restarts, only manually trusted worktrees are. This ensures that new trust decisions must be made if a users elects to disable the `trust_all_worktrees` setting.
+Auto-trusted worktrees are not persisted between restarts; only manually trusted worktrees are. This ensures users make new trust decisions if they later disable `trust_all_worktrees`.
## Trust hierarchy
-These are mostly internal details and may change in the future, but are helpful to understand how multiple different trust requests can be approved at once.
+These are mostly internal details and may change, but they help explain how multiple trust requests can be approved at once.
Zed has multiple layers of trust, based on the requests, from the least to most trusted level:
- "single file worktree"
-After opening an empty Zed it's possible to open just a file, same as after opening a directory in Zed it's possible to open a file outside of this directory.
-A typical scenario where a directory might be open and a single file is subsequently opened is opening Zed's settings.json file via `zed: open settings file` command: that starts a language server for a new file open, which originates from a newly created, single file worktree.
+After opening an empty Zed window, you can open a single file. You can also open a file outside the current directory after opening a directory.
+A common example is `zed: open settings file`, which may start a language server for that file and create a new single-file worktree.
Spawning a language server presents a risk should the language server experience a supply-chain attack; therefore, Zed restricts that by default. Each single file worktree requires a separate trust grant, unless the directory containing it is trusted or all worktrees are trusted.
- "directory worktree"
-If a directory is open in Zed, it's a full worktree which may spawn multiple language servers associated with it or spawn MCP servers if contained in a project settings file.Therefore, each directory worktree requires a separate trust grant unless a parent directory worktree trust is granted (see below).
+If a directory is open in Zed, it is a full worktree. It may spawn multiple language servers and MCP servers defined in project settings. Each directory worktree therefore requires a separate trust grant unless a parent-directory trust grant exists (see below).
When a directory worktree is trusted, language and MCP servers are permitted to be downloaded and started, hence we also enable single file worktree trust for the host in question automatically when this occurs: this helps when opening single files when using language server features in the trusted directory worktree.