diff --git a/.factory/skills/brand-writer/SKILL.md b/.factory/skills/brand-writer/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..12ec9344365c088206401bed1659470a199ebace --- /dev/null +++ b/.factory/skills/brand-writer/SKILL.md @@ -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. diff --git a/.factory/skills/brand-writer/rubric.md b/.factory/skills/brand-writer/rubric.md new file mode 100644 index 0000000000000000000000000000000000000000..ca84e9a106e54aa440acf3fb6a0659f7d57ac2d7 --- /dev/null +++ b/.factory/skills/brand-writer/rubric.md @@ -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. diff --git a/.factory/skills/brand-writer/taboo-phrases.md b/.factory/skills/brand-writer/taboo-phrases.md new file mode 100644 index 0000000000000000000000000000000000000000..c0d72fd8fca5d472e6892db1cf03fc1796d120c0 --- /dev/null +++ b/.factory/skills/brand-writer/taboo-phrases.md @@ -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 diff --git a/.factory/skills/brand-writer/voice-examples.md b/.factory/skills/brand-writer/voice-examples.md new file mode 100644 index 0000000000000000000000000000000000000000..ac7f013bf266afad927aacafb4d27c5243754324 --- /dev/null +++ b/.factory/skills/brand-writer/voice-examples.md @@ -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 | diff --git a/docs/src/ai/agent-panel.md b/docs/src/ai/agent-panel.md index a1ab1e6cde56f4b0ae0cf2ee69e2fdb67edf88ed..adee09a861ac655fef72b2a042db188cedf8ea62 100644 --- a/docs/src/ai/agent-panel.md +++ b/docs/src/ai/agent-panel.md @@ -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. diff --git a/docs/src/ai/agent-settings.md b/docs/src/ai/agent-settings.md index 52e6de27101415aafad3c1c006efadb24f8944c1..9995062b07afa359e2e2c5fd3b439c5a0311ad84 100644 --- a/docs/src/ai/agent-settings.md +++ b/docs/src/ai/agent-settings.md @@ -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] { diff --git a/docs/src/ai/ai-improvement.md b/docs/src/ai/ai-improvement.md index 6ae4832377b66a310ed0dc34eeae09ef33380dff..94085058f237b942f29d43f8d82b2f0afa97a782 100644 --- a/docs/src/ai/ai-improvement.md +++ b/docs/src/ai/ai-improvement.md @@ -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] { diff --git a/docs/src/ai/configuration.md b/docs/src/ai/configuration.md index 3be488f361fc6db3dff78e05b84ea5bbb1099cb2..28ec021accf2c40c1a84a8994a68f9f367d84498 100644 --- a/docs/src/ai/configuration.md +++ b/docs/src/ai/configuration.md @@ -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] { diff --git a/docs/src/ai/edit-prediction.md b/docs/src/ai/edit-prediction.md index bc8a22749a7e1fc1956454c0750ffd660870e3e1..dbb4fbef797dd1df54fe6b8f547b71683b6dbcf2 100644 --- a/docs/src/ai/edit-prediction.md +++ b/docs/src/ai/edit-prediction.md @@ -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] { diff --git a/docs/src/ai/external-agents.md b/docs/src/ai/external-agents.md index 5adeb9306658b11ed948d49f7376a09d7622bd92..ca556476b7ffcc3752258bebf2b722a7e3ceeae9 100644 --- a/docs/src/ai/external-agents.md +++ b/docs/src/ai/external-agents.md @@ -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] { diff --git a/docs/src/ai/inline-assistant.md b/docs/src/ai/inline-assistant.md index 8c9463351ac42fc2224e661acbef54af89044917..05fafa336e4f6a2d28e970ca51beea4250b08b9c 100644 --- a/docs/src/ai/inline-assistant.md +++ b/docs/src/ai/inline-assistant.md @@ -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] { diff --git a/docs/src/ai/llm-providers.md b/docs/src/ai/llm-providers.md index 79c8f0f2fed22412b35730af1652b60f88f25d5d..2c01d1a8ca5a4d9e53077d5600b100c3a43e145a 100644 --- a/docs/src/ai/llm-providers.md +++ b/docs/src/ai/llm-providers.md @@ -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] { diff --git a/docs/src/ai/mcp.md b/docs/src/ai/mcp.md index d82d7f04a85126cad7467b2a34489ec5a38a0f4b..51d5e4df5a71df7c95ae62307f6e8d9bed92c6d2 100644 --- a/docs/src/ai/mcp.md +++ b/docs/src/ai/mcp.md @@ -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] { diff --git a/docs/src/ai/privacy-and-security.md b/docs/src/ai/privacy-and-security.md index de0baf17958961ad0811d313c6cb6f93b7495d1a..5eac8a43268865920825557aa8f5a20ec9e04839 100644 --- a/docs/src/ai/privacy-and-security.md +++ b/docs/src/ai/privacy-and-security.md @@ -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 diff --git a/docs/src/ai/text-threads.md b/docs/src/ai/text-threads.md index e7aad64d475f8c4221c2571067608c0951945800..82ea45510edcd1a74e21477333f6633cd800f217 100644 --- a/docs/src/ai/text-threads.md +++ b/docs/src/ai/text-threads.md @@ -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. diff --git a/docs/src/ai/tool-permissions.md b/docs/src/ai/tool-permissions.md index 5ef8ca2d35f86a388eaf0234b64e4c0d869d78e6..61f241728f80efcec25ddc5a116ceb511596f4ef 100644 --- a/docs/src/ai/tool-permissions.md +++ b/docs/src/ai/tool-permissions.md @@ -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] { diff --git a/docs/src/all-actions.md b/docs/src/all-actions.md index e5a45a8fd8d5926e657d6ad35234fd14d4853952..e42e1ed2083b8b4146554857ffd09e0cdb25e9fd 100644 --- a/docs/src/all-actions.md +++ b/docs/src/all-actions.md @@ -1,3 +1,8 @@ +--- +title: All Actions +description: "Complete reference of all available actions and commands in Zed." +--- + # All Actions {#ACTIONS_TABLE#} diff --git a/docs/src/authentication.md b/docs/src/authentication.md index 0ea97040a0ae2023143beb5a83d15cd9e28c9786..0f3dd2ecbce95b87a3f017a1c6107d6ed0a3538d 100644 --- a/docs/src/authentication.md +++ b/docs/src/authentication.md @@ -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. diff --git a/docs/src/collaboration/channels.md b/docs/src/collaboration/channels.md index 46753a25302af95fb62463003f195dffefba7239..a07979fc0191609d73dbe4c8328e50facdbaccbf 100644 --- a/docs/src/collaboration/channels.md +++ b/docs/src/collaboration/channels.md @@ -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 diff --git a/docs/src/collaboration/contacts-and-private-calls.md b/docs/src/collaboration/contacts-and-private-calls.md index f011fa2c672c2e6e563e65172705115802262a7e..0a96ce87b6e7e3c3ffbeb0c8f4ae04fc4593e291 100644 --- a/docs/src/collaboration/contacts-and-private-calls.md +++ b/docs/src/collaboration/contacts-and-private-calls.md @@ -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 ` -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._ diff --git a/docs/src/collaboration/overview.md b/docs/src/collaboration/overview.md index 719aa56ee3b62c8562cd03ff8dd29faf25f2df5b..ce74a74ddc6c831433ce64dd67701fd221cf1eb3 100644 --- a/docs/src/collaboration/overview.md +++ b/docs/src/collaboration/overview.md @@ -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. diff --git a/docs/src/command-palette.md b/docs/src/command-palette.md index 703cce561b7ab46ddac49b94d93840bce8d66c6a..89f7fc6c60609cd403e22641a6705f8e4475e180 100644 --- a/docs/src/command-palette.md +++ b/docs/src/command-palette.md @@ -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}. ![The opened Command Palette](https://zed.dev/img/features/command-palette.jpg) -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. diff --git a/docs/src/development.md b/docs/src/development.md index 8f341dbb1506d4a6fa6c3ffa21960191ec5ecfcf..529ce2a69c08f2d3ebb77a5747762de642a1f841 100644 --- a/docs/src/development.md +++ b/docs/src/development.md @@ -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 diff --git a/docs/src/development/debuggers.md b/docs/src/development/debuggers.md index 11f49390d41b89cfb1f527e1adabfd8b1b6d401a..3f1705fa427f771f4d34167531857da8f57c1ccb 100644 --- a/docs/src/development/debuggers.md +++ b/docs/src/development/debuggers.md @@ -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 rust-lldb -p ``` -Where `` is the process ID of the Zed instance you want to attach to. +`` 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). diff --git a/docs/src/development/debugging-crashes.md b/docs/src/development/debugging-crashes.md index 9da3f8806660fb5ca0e66d3ef7db509c4efe1544..0d0743b5d22791283ce1ea7704b04affc36ac968 100644 --- a/docs/src/development/debugging-crashes.md +++ b/docs/src/development/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/.dmp -o minidump.dmp minidump-stackwalk minidump.dmp ``` -Alongside the minidump file in your logs dir, there should be a `.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 `.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). diff --git a/docs/src/development/freebsd.md b/docs/src/development/freebsd.md index 199e653a65c5cf3d86881c4c038677d60ac2fec5..6d36bb8404ad3e49ba026036bc53a13877710d6c 100644 --- a/docs/src/development/freebsd.md +++ b/docs/src/development/freebsd.md @@ -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. diff --git a/docs/src/development/glossary.md b/docs/src/development/glossary.md index 0e0f984e214fe1a46e0aff790ab5e85bb46a8674..720c20c3bd42074b3e2b4863b879a54001d27e73 100644 --- a/docs/src/development/glossary.md +++ b/docs/src/development/glossary.md @@ -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. diff --git a/docs/src/languages/scala.md b/docs/src/languages/scala.md index fc169bf229373fcad47cc6bb752b306212596099..0f3b0018bb1365e3520f2802f6942df420420c97 100644 --- a/docs/src/languages/scala.md +++ b/docs/src/languages/scala.md @@ -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). diff --git a/docs/src/languages/scheme.md b/docs/src/languages/scheme.md index 59e7ae1ddf62f83fc4ab0e66c9b3539d741c5f2f..975c09d94e93e0aba9fb6214f214b401cf7cba51 100644 --- a/docs/src/languages/scheme.md +++ b/docs/src/languages/scheme.md @@ -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). diff --git a/docs/src/languages/sh.md b/docs/src/languages/sh.md index cf88c89bfa29fd12390640a64cb4826678cfa9f5..b122274673c5eea0c6311d4a0e1f0069e4bafb08 100644 --- a/docs/src/languages/sh.md +++ b/docs/src/languages/sh.md @@ -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": { diff --git a/docs/src/languages/sql.md b/docs/src/languages/sql.md index fd257c9ab0924db9bbc3ffc596a5992ead0dc211..28a617143a2bf33a3ce2c2994f727cf647d2edab 100644 --- a/docs/src/languages/sql.md +++ b/docs/src/languages/sql.md @@ -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": { diff --git a/docs/src/languages/svelte.md b/docs/src/languages/svelte.md index 941c8fdf9bfb1233665bda7579fb8de453a4b7ed..787654367f4456ae77f1fc729cb1655bd107f32d 100644 --- a/docs/src/languages/svelte.md +++ b/docs/src/languages/svelte.md @@ -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). diff --git a/docs/src/languages/swift.md b/docs/src/languages/swift.md index 1492942fe8d33e63949ad0037b12405c373a9770..b53b0744b96a71bf1dd5f217700fab89b9b4ae9b 100644 --- a/docs/src/languages/swift.md +++ b/docs/src/languages/swift.md @@ -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). diff --git a/docs/src/languages/tailwindcss.md b/docs/src/languages/tailwindcss.md index 30316e516f413ae8e7b5c7fdfd7f9b03ae43d04d..72e3ca3955e3b2f95455b06b40860e1161c8e4fa 100644 --- a/docs/src/languages/tailwindcss.md +++ b/docs/src/languages/tailwindcss.md @@ -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] { diff --git a/docs/src/languages/terraform.md b/docs/src/languages/terraform.md index c1ff03a83a4da8d08639bc64dc354671fd66f5cc..a7f87d20f46fb90616abb33a28b64d8e913ddcdd 100644 --- a/docs/src/languages/terraform.md +++ b/docs/src/languages/terraform.md @@ -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). diff --git a/docs/src/languages/toml.md b/docs/src/languages/toml.md index 46b93b67eb4ba85dea0c297adbfe1a261b6a22dc..df4f2cb9486e0326344b5fc6b1a58e32196882bb 100644 --- a/docs/src/languages/toml.md +++ b/docs/src/languages/toml.md @@ -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). diff --git a/docs/src/languages/typescript.md b/docs/src/languages/typescript.md index d4fccc38f8a460e9ec097dee249a6441bd34a344..25ec709e565df86019b49b37dac9059a2bb7c880 100644 --- a/docs/src/languages/typescript.md +++ b/docs/src/languages/typescript.md @@ -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] { diff --git a/docs/src/languages/uiua.md b/docs/src/languages/uiua.md index 622e04fc3d348bd20e8019c6b996a002fe19801f..889c57e619c65aee5adbdea628df3c1f66ee75a8 100644 --- a/docs/src/languages/uiua.md +++ b/docs/src/languages/uiua.md @@ -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. diff --git a/docs/src/languages/vue.md b/docs/src/languages/vue.md index d4a1f8c3097a5fecb41f5496ccc75dce782adb81..607d2b18a5243a5b552db96308faab6aebeb8b6c 100644 --- a/docs/src/languages/vue.md +++ b/docs/src/languages/vue.md @@ -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). diff --git a/docs/src/languages/xml.md b/docs/src/languages/xml.md index 4397249e6973530064be3f4aebf8bfaee6b55ddb..250657b3bb75d29a4d4b91f98394a8dbb359ce95 100644 --- a/docs/src/languages/xml.md +++ b/docs/src/languages/xml.md @@ -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/). diff --git a/docs/src/languages/yaml.md b/docs/src/languages/yaml.md index 33b92df94ec59f6f4cdf9a0afe83c3ad74dc3bda..ee5861e0d2b58565948cff4dc7de5a5c667b3b85 100644 --- a/docs/src/languages/yaml.md +++ b/docs/src/languages/yaml.md @@ -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": { diff --git a/docs/src/languages/yara.md b/docs/src/languages/yara.md index ba31a97dedc97d7a4c7a4925b30302ab4e33ba57..6b7b78e4d48cf880f345fbc89899d04b9d050d8d 100644 --- a/docs/src/languages/yara.md +++ b/docs/src/languages/yara.md @@ -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). diff --git a/docs/src/languages/yarn.md b/docs/src/languages/yarn.md index 035fe34069433436109013156acfa95087738966..399d8bdd9d36202f81296d7c4ba5465d21101fda 100644 --- a/docs/src/languages/yarn.md +++ b/docs/src/languages/yarn.md @@ -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. diff --git a/docs/src/languages/zig.md b/docs/src/languages/zig.md index 4a48405d0c1899b6633c615b4252b439a052fa23..666b21253fc336db8af8fe03ac9a7b4f83414da5 100644 --- a/docs/src/languages/zig.md +++ b/docs/src/languages/zig.md @@ -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). diff --git a/docs/src/linux.md b/docs/src/linux.md index 8df550b22754a4d42e4475fb3df4d745f3a433e4..b1a82c332fa2ab1dde32762540e13a211e1ab3e8 100644 --- a/docs/src/linux.md +++ b/docs/src/linux.md @@ -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 diff --git a/docs/src/macos.md b/docs/src/macos.md index 3cbd700a1aac87e30839f4d32942d07b721a4c3f..4c95c86122f7e17a3e4b91d925b3fdda3effd8f2 100644 --- a/docs/src/macos.md +++ b/docs/src/macos.md @@ -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. diff --git a/docs/src/migrate/intellij.md b/docs/src/migrate/intellij.md index 14b245879e4c0e982706ec7ca43967bff6227166..7916d69f8c4a58ddfd2e503614e32dfbfbcedb98 100644 --- a/docs/src/migrate/intellij.md +++ b/docs/src/migrate/intellij.md @@ -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 { diff --git a/docs/src/migrate/pycharm.md b/docs/src/migrate/pycharm.md index e633e32bd7ec1a5b642c9d2ffe8bc68236bd1a7b..4492bf1cbff3c965e03d2fadbae4a0c982a9172d 100644 --- a/docs/src/migrate/pycharm.md +++ b/docs/src/migrate/pycharm.md @@ -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 { diff --git a/docs/src/migrate/rustrover.md b/docs/src/migrate/rustrover.md index c9edac687fa239a8a5f3eb3c16bfbc53e81d7e7b..aeaf57d2363f78aea6be9cf3e5092c2931d45ade 100644 --- a/docs/src/migrate/rustrover.md +++ b/docs/src/migrate/rustrover.md @@ -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 { diff --git a/docs/src/migrate/vs-code.md b/docs/src/migrate/vs-code.md index c95538b4ccdb25e76d8f2e0f8af8d3c4736587bd..951cd6b1f3649340d5f04c14faf486010d85a238 100644 --- a/docs/src/migrate/vs-code.md +++ b/docs/src/migrate/vs-code.md @@ -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 diff --git a/docs/src/migrate/webstorm.md b/docs/src/migrate/webstorm.md index a30b861ff6df4e960a3228e086a550a643676ef5..a9304714b58ec8d1e93d063f2a9a94bbbd93c340 100644 --- a/docs/src/migrate/webstorm.md +++ b/docs/src/migrate/webstorm.md @@ -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 { diff --git a/docs/src/performance.md b/docs/src/performance.md index 544e39e94babbf9c335a847af8819ad5b00494d1..09abecdeffe4e268413a73b189ef301511b1a20e 100644 --- a/docs/src/performance.md +++ b/docs/src/performance.md @@ -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) diff --git a/docs/src/reference/all-settings.md b/docs/src/reference/all-settings.md index 4aaf979993802da20d0b1a0f43d1a1323008611c..b32d75b9ab5cdc654f13f01f4b08f36b6e03f6b5 100644 --- a/docs/src/reference/all-settings.md +++ b/docs/src/reference/all-settings.md @@ -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. diff --git a/docs/src/reference/cli.md b/docs/src/reference/cli.md index e7d5695de2fdbce3e70b70641786eafe1c713be2..166b06a095b7c73f4322acdf65a4af46106ade5e 100644 --- a/docs/src/reference/cli.md +++ b/docs/src/reference/cli.md @@ -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 diff --git a/docs/src/reference/default-key-bindings.md b/docs/src/reference/default-key-bindings.md index 14f7267aec135c3183a155e67dff39b7d1c6d27d..cdab04ece5d1038eddd3f69ed5d182a291718e41 100644 --- a/docs/src/reference/default-key-bindings.md +++ b/docs/src/reference/default-key-bindings.md @@ -1 +1,6 @@ +--- +title: Default Key Bindings +description: "Reference for Zed's default key bindings." +--- + # Default Key Bindings diff --git a/docs/src/remote-development.md b/docs/src/remote-development.md index c0161c65376a7545245f8efc7ce587892f38edfa..4ea6c5856d43f8ca05779ed9933656f131586771 100644 --- a/docs/src/remote-development.md +++ b/docs/src/remote-development.md @@ -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. diff --git a/docs/src/repl.md b/docs/src/repl.md index 7e8b590153b5500859dc3a84d4a222cf8fdd887d..0bfbfd093a7f23b8b3db777888efff4b6f11a0df 100644 --- a/docs/src/repl.md +++ b/docs/src/repl.md @@ -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.