From 95b0930c7228237753fd0cd69268542c3cb58fe1 Mon Sep 17 00:00:00 2001 From: Katie Geer Date: Thu, 18 Dec 2025 12:39:37 -0800 Subject: [PATCH] Fix Prettier formatting issues --- docs/src/appearance.md | 10 +- docs/src/configuring-zed.md | 3 + docs/src/migrate/pycharm.md | 16 +- docs/src/migrate/rustrover.md | 5 +- docs/src/reference/cli.md | 8 +- docs/temp_ia_organization.md | 380 ++++++++++++++++++++++++++++++++++ 6 files changed, 401 insertions(+), 21 deletions(-) create mode 100644 docs/temp_ia_organization.md diff --git a/docs/src/appearance.md b/docs/src/appearance.md index ac5b389ca83fb9090ecacabb4921cb0850ce179c..674714af8657a11f36ac19fb32707c6e125b6cea 100644 --- a/docs/src/appearance.md +++ b/docs/src/appearance.md @@ -60,11 +60,11 @@ Like color themes, icon themes support separate light and dark variants: Zed uses three font settings for different contexts: -| Setting | Used for | -|---------|----------| -| `buffer_font_family` | Editor text | -| `ui_font_family` | Interface elements | -| `terminal.font_family` | Terminal | +| Setting | Used for | +| ---------------------- | ------------------ | +| `buffer_font_family` | Editor text | +| `ui_font_family` | Interface elements | +| `terminal.font_family` | Terminal | Example configuration: diff --git a/docs/src/configuring-zed.md b/docs/src/configuring-zed.md index 50b09e041ee449993c0b1a59a48e81e2ee2bf4d0..9bec490e5a3f505ca7ff2e040ab5e86a6eb6f9c1 100644 --- a/docs/src/configuring-zed.md +++ b/docs/src/configuring-zed.md @@ -9,6 +9,7 @@ For visual customization (themes, fonts, icons), see [Appearance](./appearance.m The **Settings Editor** ({#kb zed::OpenSettings}) is the primary way to configure Zed. It provides a searchable interface where you can browse available settings, see their current values, and make changes. To open it: + - Press {#kb zed::OpenSettings} - Or run `zed: open settings` from the command palette @@ -23,6 +24,7 @@ As you type in the search box, matching settings appear with descriptions and co Your user settings apply globally across all projects. Open the file with {#kb zed::OpenSettingsFile} or run `zed: open settings file` from the command palette. The file is located at: + - macOS: `~/.config/zed/settings.json` - Linux: `~/.config/zed/settings.json` (or `$XDG_CONFIG_HOME/zed/settings.json`) - Windows: `%APPDATA%\Zed\settings.json` @@ -81,6 +83,7 @@ Use different settings for Stable, Preview, or Nightly builds by adding top-leve ``` With this configuration: + - **Stable** uses One Dark with vim mode off - **Preview** uses Catppuccin Mocha with vim mode off - **Nightly** uses Rosé Pine with vim mode on diff --git a/docs/src/migrate/pycharm.md b/docs/src/migrate/pycharm.md index f8e8bd7749cebbf1435031f5e5be5730c602f149..636bc69eeba1c09b3e0e8a0d74ccd859aedbb342 100644 --- a/docs/src/migrate/pycharm.md +++ b/docs/src/migrate/pycharm.md @@ -259,14 +259,14 @@ Zed has none of this. The language server sees Python code as Python code—it d PyCharm organizes auxiliary views into numbered tool windows (Project = 1, Python Console = 4, Terminal = Alt+F12, etc.). Zed uses a similar concept called "docks": -| PyCharm Tool Window | Zed Equivalent | Shortcut (JetBrains keymap) | -| -------------------- | -------------- | --------------------------- | -| Project (1) | Project Panel | `Cmd + 1` | -| Git (9 or Cmd+0) | Git Panel | `Cmd + 0` | -| Terminal (Alt+F12) | Terminal Panel | `Alt + F12` | -| Structure (7) | Outline Panel | `Cmd + 7` | -| Problems (6) | Diagnostics | `Cmd + 6` | -| Debug (5) | Debug Panel | `Cmd + 5` | +| PyCharm Tool Window | Zed Equivalent | Shortcut (JetBrains keymap) | +| ------------------- | -------------- | --------------------------- | +| Project (1) | Project Panel | `Cmd + 1` | +| Git (9 or Cmd+0) | Git Panel | `Cmd + 0` | +| Terminal (Alt+F12) | Terminal Panel | `Alt + F12` | +| Structure (7) | Outline Panel | `Cmd + 7` | +| Problems (6) | Diagnostics | `Cmd + 6` | +| Debug (5) | Debug Panel | `Cmd + 5` | Zed has three dock positions: left, bottom, and right. Panels can be moved between docks by dragging or through settings. diff --git a/docs/src/migrate/rustrover.md b/docs/src/migrate/rustrover.md index 943401f2a2d23b8a318cbc7490d03653a94e04d5..4d0e85cfe9b981243044290929070e87876987d3 100644 --- a/docs/src/migrate/rustrover.md +++ b/docs/src/migrate/rustrover.md @@ -482,10 +482,7 @@ If you work with multiple Cargo projects that aren't in a workspace, you can tel "lsp": { "rust-analyzer": { "initialization_options": { - "linkedProjects": [ - "./project-a/Cargo.toml", - "./project-b/Cargo.toml" - ] + "linkedProjects": ["./project-a/Cargo.toml", "./project-b/Cargo.toml"] } } } diff --git a/docs/src/reference/cli.md b/docs/src/reference/cli.md index 1b5b979a5faa700bbf6b12667fc27364488a55ac..e7d5695de2fdbce3e70b70641786eafe1c713be2 100644 --- a/docs/src/reference/cli.md +++ b/docs/src/reference/cli.md @@ -183,9 +183,9 @@ On Windows, the CLI supports opening paths from WSL distributions. This is handl ## Exit Codes -| Code | Meaning | -|------|---------| -| `0` | Success | -| `1` | Error (details printed to stderr) | +| Code | Meaning | +| ---- | --------------------------------- | +| `0` | Success | +| `1` | Error (details printed to stderr) | When using `--wait`, the exit code reflects whether the files were saved before closing. diff --git a/docs/temp_ia_organization.md b/docs/temp_ia_organization.md new file mode 100644 index 0000000000000000000000000000000000000000..d9636386576fbbc8886975319e7454919123967d --- /dev/null +++ b/docs/temp_ia_organization.md @@ -0,0 +1,380 @@ +# Proposed Zed Documentation Information Architecture + +This document outlines a proposed restructuring of Zed's documentation to improve discoverability, separate task-oriented content from reference material, and better serve users with different goals (new users, migrating users, power users). + +--- + +## Proposed IA Structure + +```markdown +# Get Started + +- Welcome # Hub page with job-to-be-done cards +- Installation +- Your First 10 Minutes in Zed # True quickstart: open project → write code → use AI → run +- Key Concepts # Mental models: workspaces, buffers, panels, command palette + +# Quickstarts # Task-focused, 5-10 min each + +- Set Up AI in Zed +- Work on a Remote Server +- Configure Your Language +- Customize Zed to Feel Like Home + +# Coming From... # Migration guides + +- VS Code +- Vim / Neovim +- JetBrains +- Cursor + +# AI # Key differentiator - prominent placement + +- Overview +- Agent Panel + - Tools + - External Agents +- Inline Assistant +- Edit Prediction +- Text Threads +- Rules +- Model Context Protocol +- Configuration + - LLM Providers + - Agent Settings +- Subscription + - Billing + - Models + - Plans and Usage + +# Working with Code # Daily workflow, organized by job + +- Overview # Walkthrough: open → edit → navigate → run → commit +- Editing Code + - Code Completions + - Snippets + - Formatting & Linting + - Diagnostics & Quick Fixes + - Multibuffers +- Finding & Navigating + - Command Palette + - File Finder & Project Search + - Go to Definition & Symbol Search + - Outline Panel +- Running & Testing + - Tasks + - Terminal + - Debugger + - REPL +- Git + +# Collaboration + +- Overview +- Channels +- Private Calls + +# Remote Development + +- Overview +- SSH Connections +- Dev Containers + +# Languages + +- Overview # Hub with capability tags (LSP, Debug, Format, etc.) +- Configuring Languages + - Toolchains +- Popular Languages # Curated, workflow-focused + - Python + - JavaScript / TypeScript + - Rust + - Go + - C / C++ +- All Languages # Searchable/filterable reference + +# Customization # Personalization, organized by goal + +- Overview # "Customize in 5 minutes" + how settings work +- Appearance + - Themes + - Icon Themes + - Fonts & Visual Tweaks +- Keybindings + - Custom Key Bindings + - Vim Mode + - Helix Mode +- Snippets + +# Extensions + +- Overview +- Installing Extensions +- Developing Extensions +- Extension Capabilities +- Extension Types + - Language Extensions + - Theme Extensions + - Icon Theme Extensions + - Debugger Extensions + - Slash Command Extensions + - Agent Server Extensions + - MCP Server Extensions + +# Reference # Lookup-only, not for reading + +- All Settings +- All Actions +- Default Key Bindings +- CLI Reference +- Environment Variables +- Glob Patterns + +# Platform Support + +- macOS +- Windows +- Linux + +# Account & Privacy + +- Sign In +- Privacy and Security +- Telemetry + +# Troubleshooting + +- Common Issues +- Performance +- Update +- Uninstall + +# Developing Zed + +- Contributing +- Building from Source + - macOS + - Linux + - Windows + - FreeBSD +- Local Collaboration +- Using Debuggers +- Glossary +- Release Notes +``` + +--- + +## Deep Dive: Working with Code + +This section replaces the current "Using Zed" catch-all. Instead of listing features, it's organized around **what users are trying to accomplish** in their daily workflow. + +### Design Principles + +1. **Overview as workflow guide**: The overview page walks through a typical session (open project → write code → find things → run/test → commit), linking to detailed pages +2. **Group by job, not feature**: "Finding & Navigating" groups file finder, symbol search, go-to-definition, and outline because they all serve the job of "I need to find something" +3. **Progressive disclosure**: Start with the common case, link to advanced topics + +### Proposed Structure + +**Working with Code** + +``` +Overview +├── "A day in Zed" walkthrough +├── Links to each sub-section +└── Quick tips for common tasks + +Editing Code +├── Code Completions (LSP, AI-powered, snippets integration) +├── Snippets (creating, using, language-specific) +├── Formatting & Linting (format on save, linter integration) +├── Diagnostics & Quick Fixes (error navigation, code actions) +└── Multibuffers (what they are, when to use them) + +Finding & Navigating +├── Command Palette (the hub for everything) +├── File Finder & Project Search (fuzzy find, ripgrep, filters) +├── Go to Definition & Symbol Search (LSP navigation, workspace symbols) +└── Outline Panel (file structure, breadcrumbs) + +Running & Testing +├── Tasks (defining, running, task templates) +├── Terminal (integrated terminal, shell integration) +├── Debugger (breakpoints, stepping, variables, DAP) +└── REPL (interactive development, Jupyter-style) + +Git +├── Staging & committing +├── Branches +├── Diff view +├── Blame & history +└── (future: GitHub integration) + +``` + +### What This Replaces + +| Current "Using Zed" Item | New Location | +| ------------------------ | ---------------------------------------- | +| Multibuffers | Working with Code → Editing Code | +| Command Palette | Working with Code → Finding & Navigating | +| Command-line Interface | Reference → CLI Reference | +| Outline Panel | Working with Code → Finding & Navigating | +| Code Completions | Working with Code → Editing Code | +| Collaboration | Collaboration (top-level section) | +| Git | Working with Code → Git | +| Debugger | Working with Code → Running & Testing | +| Diagnostics | Working with Code → Editing Code | +| Tasks | Working with Code → Running & Testing | +| Remote Development | Remote Development (top-level section) | +| Dev Containers | Remote Development | +| Environment Variables | Reference | +| REPL | Working with Code → Running & Testing | + +--- + +## Deep Dive: Customization + +This section replaces "Configuration" and reframes it around **user goals** rather than settings categories. + +### Design Principles + +1. **Start with outcomes**: Users don't want to "configure settings" — they want Zed to look and feel a certain way +2. **Quick wins first**: Overview page shows how to customize the essentials in 5 minutes +3. **Explain the system**: Help users understand how settings work (JSON, project vs global, settings UI, deep links) +4. **Separate appearance from behavior**: Visual customization is different from keybinding customization + +### Proposed Structure + +**Customization** + +``` +Overview +├── "Customize Zed in 5 minutes" quick guide +├── How settings work (JSON, project vs global, settings UI) +├── Using settings deep links +└── Links to detailed sections + +Appearance +├── Themes (installing, switching, creating) +├── Icon Themes +├── Fonts & Visual Tweaks (UI density, status bar, tab bar, etc.) + +Keybindings +├── Custom Key Bindings (understanding the keymap, common customizations) +├── Vim Mode (setup, differences from native vim, customization) +├── Helix Mode (setup, key differences) + +Snippets +├── Using snippets +├── Creating custom snippets +├── Language-specific snippets + +``` + +### What This Replaces + +| Current "Configuration" Item | New Location | +| ---------------------------- | --------------------------------- | +| Configuring Zed | Reference → All Settings | +| Configuring Languages | Languages → Configuring Languages | +| Key bindings | Customization→ Keybindings | +| All Actions | Reference → All Actions | +| Snippets | Customization→ Snippets | +| Themes | Customization→ Appearance | +| Icon Themes | Customization→ Appearance | +| Visual Customization | Customization→ Appearance | +| Vim Mode | Customization→ Keybindings | +| Helix Mode | Customization→ Keybindings | + +### Key Insight: Settings Reference vs. Customization Guide + +The current `configuring-zed.md` is a **reference** (lookup all 200+ settings). That belongs in the Reference section. + +"Making Zed Yours" is a **guide** that helps users accomplish goals: + +- "I want Zed to look like my old editor" → Themes, fonts +- "I want to use my vim muscle memory" → Vim Mode +- "I want to change what ⌘+P does" → Custom Key Bindings + +The guide pages should link to the reference when users need to look up specific settings. + +--- + +## Summary of Changes + +| Current | Proposed | Rationale | +| ------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ | +| Getting Started (5 items) | Get Started (4) + Quickstarts (4) + Coming From... (4) | Split welcome/install from task-focused quickstarts and migration guides | +| Configuration (9 items, front-loaded) | Customization(goal-oriented) + Reference | Users want outcomes, not settings; reference is for lookup | +| Using Zed (14 items, catch-all) | Working with Code (job-organized) + Collaboration + Remote Dev | Group by workflow: editing, navigating, running, git | +| AI (section 5) | AI (section 4) | Promote key differentiator | +| Language Support (60+ flat list) | Languages with Popular grouping + filterable All Languages | Reduce cognitive load, highlight common languages | +| No Reference section | Reference (6 items) | Explicitly label lookup-only content | +| Troubleshooting in Getting Started | Troubleshooting as dedicated section | Easier to find when users need help | + +--- + +## Content Gaps: New Pages Needed + +### Get Started & Quickstarts + +- `welcome.md` - Hub page with job-to-be-done cards +- `first-10-minutes.md` - True quickstart walkthrough +- `concepts.md` - Mental models for Zed +- `quickstarts/ai-setup.md` +- `quickstarts/remote-dev.md` +- `quickstarts/language-setup.md` +- `quickstarts/customize.md` + +### Migration Guides + +- `migration/vscode.md` ✅ +- `migration/vim.md` +- `migration/jetbrains.md` +- `migration/cursor.md` + +### Working with Code + +- `working-with-code/overview.md` - "A day in Zed" walkthrough +- `working-with-code/editing/formatting-linting.md` +- `working-with-code/navigating/file-finder.md` +- `working-with-code/navigating/symbols.md` + +### Customization + +- `customization/overview.md` - "Customize in 5 minutes" + how settings work +- `customization/appearance/fonts-visual.md` + +### Platform Support + +- `platforms/macos.md` (currently missing) + +### Reference + +- `reference/default-keybindings.md` + +--- + +## Pages to Rework + +| Page | Changes Needed | +| -------------------- | ---------------------------------------------------------- | +| `configuring-zed.md` | Relabel as "All Settings" reference, add on-page filtering | +| `all-actions.md` | Add filtering by category (Agent, Editor, Git, etc.) | +| `languages.md` | Transform into filterable hub with capability tags | +| `quick-start.md` | Rewrite as true 5-10 minute walkthrough | + +--- + +## Doc Types + +Each page should be labeled with a type for clarity: + +| Type | Purpose | Example | +| -------------- | ---------------------------- | ------------------ | +| **Quickstart** | 5-10 min, end-to-end task | "Set Up AI in Zed" | +| **Guide** | Deeper task-oriented content | "Vim Mode" | +| **Concept** | Explanatory, mental models | "Key Concepts" | +| **Reference** | Lookup-only, tables/lists | "All Settings" |