Skip to content

Commit 83142cf

Browse files
ammar-agentammar-agent
authored
🤖 docs: improve design and organization (#461)
## Summary Improves documentation visual design and reorganizes workspace documentation for better clarity. ## Visual Design Improvements ### Blockquotes - Enhanced styling with support for GitHub-style alerts (Note, Tip, Important, Warning, Caution) - Color-coded left borders for each alert type - Consistent border-radius throughout ### Border-Radius - Restored consistent border-radius across all UI elements (8px/6px/4px/3px) - Fixed table border-radius rendering (switched from `border-collapse: collapse` to `separate`) - Applied to: blockquotes, code blocks, inline code, tables, details, images, mermaid diagrams ### Server Configuration - mdbook server now binds to 0.0.0.0 for remote access ## Documentation Organization ### Workspace Pages - Created dedicated `docs/local.md` for local workspace details - Simplified `docs/workspaces.md` to high-level overview - Moved reviewing sections to main Workspaces page (applies to both local and SSH) New structure: ``` Workspaces (overview + reviewing workflows) ├── Local (git worktrees specifics) ├── SSH (remote workspaces) ├── Forking └── Init Hooks ``` ## Development Setup - Added mdbook tools to nix devShell for easier local development --- _Generated with `cmux`_
1 parent 9013859 commit 83142cf

File tree

6 files changed

+170
-55
lines changed

6 files changed

+170
-55
lines changed

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
# Features
1010

1111
- [Workspaces](./workspaces.md)
12+
- [Local](./local.md)
1213
- [SSH](./ssh.md)
1314
- [Forking](./fork.md)
1415
- [Init Hooks](./init-hooks.md)

‎docs/local.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Local Workspaces
2+
3+
Local workspaces use [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine. Worktrees share the `.git` directory with your main repository while maintaining independent working changes and checkout state.
4+
5+
## How Worktrees Work
6+
7+
A worktree is a separate directory on the same filesystem as the main repository that shares a `.git` but has independent working changes and checkout state. **All committed changes from any worktree are visible to all other worktrees including the main repository.**
8+
9+
It's important to note that a **worktree is not locked to a branch**. The agent can switch to new branches, enter a detached HEAD state, etc. When you create a workspace, the agent will begin at the selected branch but may switch freely in the course of the session. **We empower users to define their agent's branching strategy in AGENTS.md**
10+
11+
## Filesystem Layout
12+
13+
Local workspaces are stored in `~/.cmux/src/<project-name>/<workspace-name>`.
14+
15+
Example layout:
16+
17+
```
18+
~/.cmux/src/
19+
cmux-main/
20+
improved-auth-ux/
21+
fix-ci-flakes/
22+
```

‎docs/theme/custom.css‎

Lines changed: 111 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@
2727
--link-color: rgb(62, 140, 218);
2828
--link-hover: var(--color-plan-mode-hover);
2929
--content-max-width: 78ch;
30-
--radius-lg: 10px;
31-
--radius-md: 8px;
32-
--radius-sm: 6px;
33-
--radius-xs: 4px;
30+
--radius-lg: 8px;
31+
--radius-md: 6px;
32+
--radius-sm: 4px;
33+
--radius-xs: 3px;
3434
--shadow-1: 0 1px 1px hsl(0 0% 0% / 0.25);
3535
--shadow-2: 0 2px 10px hsl(0 0% 0% / 0.35);
3636

@@ -233,12 +233,14 @@ p:has(+ ol) {
233233
padding: 2px 6px;
234234
font-family: var(--font-monospace);
235235
font-size: 0.92em;
236+
border-radius: var(--radius-xs);
236237
}
237238

238239
/* Code blocks */
239240
pre {
240241
background: var(--color-background-secondary) !important;
241242
border: 1px solid var(--color-border) !important;
243+
border-radius: var(--radius-md);
242244
box-shadow: var(--shadow-1);
243245
overflow: auto;
244246
margin: 1rem 0;
@@ -259,23 +261,52 @@ pre > code {
259261

260262
/* Tables */
261263
table {
262-
border-collapse: collapse;
264+
border-collapse: separate;
265+
border-spacing: 0;
263266
width: 100%;
264267
margin: 1.1em 0;
265268
background: var(--color-background-secondary) !important;
269+
border: 1px solid var(--color-border);
266270
border-radius: var(--radius-md);
271+
overflow: hidden;
267272
}
268273
table thead {
269274
background: color-mix(in srgb, var(--color-background-secondary), white 8%);
270-
border-bottom: 2px solid var(--color-border) !important;
275+
}
276+
table thead tr:first-child th:first-child {
277+
border-top-left-radius: var(--radius-md);
278+
}
279+
table thead tr:first-child th:last-child {
280+
border-top-right-radius: var(--radius-md);
281+
}
282+
table tbody tr:last-child td:first-child {
283+
border-bottom-left-radius: var(--radius-md);
284+
}
285+
table tbody tr:last-child td:last-child {
286+
border-bottom-right-radius: var(--radius-md);
271287
}
272288
table th,
273289
table td {
274290
padding: 0.75em 1em;
275-
border: 1px solid var(--color-border) !important;
291+
border-right: 1px solid var(--color-border);
292+
border-bottom: 1px solid var(--color-border);
276293
text-align: left !important;
277294
color: var(--color-text) !important;
278295
}
296+
table th:first-child,
297+
table td:first-child {
298+
border-left: none;
299+
}
300+
table th:last-child,
301+
table td:last-child {
302+
border-right: none;
303+
}
304+
table thead th {
305+
border-bottom: 2px solid var(--color-border) !important;
306+
}
307+
table tbody tr:last-child td {
308+
border-bottom: none;
309+
}
279310
table th {
280311
font-weight: 700;
281312
font-size: 1.05em;
@@ -291,17 +322,82 @@ table code {
291322
font-size: 0.9em;
292323
}
293324

294-
/* Blockquotes (callout style) */
325+
/* Blockquotes with GitHub-style alerts support */
295326
blockquote {
296-
border: 1px solid var(--color-border) !important;
297-
border-left: 4px solid var(--color-plan-mode) !important;
298-
background: color-mix(in srgb, var(--color-background-secondary), white 1.5%) !important;
299-
padding: 0.5rem 0.6rem;
300-
margin: 1.2rem 0;
301-
color: color-mix(in srgb, var(--color-text), white 6%) !important;
327+
border-left: 3px solid var(--color-plan-mode);
328+
background: color-mix(in srgb, var(--color-background-secondary), white 3%);
329+
padding: 1rem 1.2rem;
330+
margin: 1.5rem 0;
331+
border-radius: var(--radius-md);
332+
color: var(--color-text);
333+
}
334+
335+
blockquote p {
336+
margin: 0.5rem 0;
302337
}
338+
339+
blockquote p:first-child {
340+
margin-top: 0;
341+
}
342+
343+
blockquote p:last-child {
344+
margin-bottom: 0;
345+
}
346+
347+
/* GitHub-style alert callouts */
348+
/* NOTE: blue */
349+
blockquote:has(p:first-child > strong:first-child:is([class*="Note"], [class*="note"])),
350+
blockquote > p:first-child:has(strong:first-child:is([class*="Note"], [class*="note"])) {
351+
border-left-color: hsl(210 70% 50%);
352+
}
353+
blockquote:has(p:first-child > strong:first-child:is([class*="Note"], [class*="note"])) p:first-child strong:first-child,
354+
blockquote > p:first-child strong:first-child:is([class*="Note"], [class*="note"]) {
355+
color: hsl(210 70% 60%) !important;
356+
}
357+
358+
/* TIP: green */
359+
blockquote:has(p:first-child > strong:first-child:is([class*="Tip"], [class*="TIP"])),
360+
blockquote > p:first-child:has(strong:first-child:is([class*="Tip"], [class*="TIP"])) {
361+
border-left-color: hsl(120 50% 45%);
362+
}
363+
blockquote:has(p:first-child > strong:first-child:is([class*="Tip"], [class*="TIP"])) p:first-child strong:first-child,
364+
blockquote > p:first-child strong:first-child:is([class*="Tip"], [class*="TIP"]) {
365+
color: hsl(120 50% 55%) !important;
366+
}
367+
368+
/* IMPORTANT: purple */
369+
blockquote:has(p:first-child > strong:first-child:is([class*="Important"], [class*="IMPORTANT"])),
370+
blockquote > p:first-child:has(strong:first-child:is([class*="Important"], [class*="IMPORTANT"])) {
371+
border-left-color: hsl(268 94% 60%);
372+
}
373+
blockquote:has(p:first-child > strong:first-child:is([class*="Important"], [class*="IMPORTANT"])) p:first-child strong:first-child,
374+
blockquote > p:first-child strong:first-child:is([class*="Important"], [class*="IMPORTANT"]) {
375+
color: hsl(268 94% 65%) !important;
376+
}
377+
378+
/* WARNING: orange/yellow */
379+
blockquote:has(p:first-child > strong:first-child:is([class*="Warning"], [class*="WARNING"])),
380+
blockquote > p:first-child:has(strong:first-child:is([class*="Warning"], [class*="WARNING"])) {
381+
border-left-color: hsl(38 92% 50%);
382+
}
383+
blockquote:has(p:first-child > strong:first-child:is([class*="Warning"], [class*="WARNING"])) p:first-child strong:first-child,
384+
blockquote > p:first-child strong:first-child:is([class*="Warning"], [class*="WARNING"]) {
385+
color: hsl(38 92% 60%) !important;
386+
}
387+
388+
/* CAUTION: red */
389+
blockquote:has(p:first-child > strong:first-child:is([class*="Caution"], [class*="CAUTION"])),
390+
blockquote > p:first-child:has(strong:first-child:is([class*="Caution"], [class*="CAUTION"])) {
391+
border-left-color: hsl(0 70% 55%);
392+
}
393+
blockquote:has(p:first-child > strong:first-child:is([class*="Caution"], [class*="CAUTION"])) p:first-child strong:first-child,
394+
blockquote > p:first-child strong:first-child:is([class*="Caution"], [class*="CAUTION"]) {
395+
color: hsl(0 70% 60%) !important;
396+
}
397+
398+
/* Default strong styling in blockquotes */
303399
blockquote strong {
304-
color: var(--color-plan-mode) !important;
400+
color: var(--color-plan-mode);
305401
}
306402

307403
/* kbd (for keybinds page) */

‎docs/workspaces.md‎

Lines changed: 29 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,50 @@
11
# Workspaces
22

3-
cmux supports multiple workspace backends for different use cases:
3+
Workspaces in cmux provide isolated development environments for parallel agent work. Each workspace maintains its own Git state, allowing you to explore different approaches, run multiple tasks simultaneously, or test changes without affecting your main repository.
44

5-
- **Local workspaces**: [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine
6-
- **SSH workspaces**: Regular git clones on a remote server accessed via SSH
5+
## Workspace Types
76

8-
The backend is selected based on your runtime configuration. Local workspaces use git worktrees which share the `.git` directory with your main repository, while SSH workspaces are independent git clones on the remote machine.
7+
cmux supports two workspace backends:
98

10-
## Basics of worktrees
9+
- **[Local Workspaces](./local.md)**: Use [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine. Worktrees share the `.git` directory with your main repository while maintaining independent working changes.
1110

12-
A worktree is a seperate directory on the same filesystem as the main repository that shares a `.git`
13-
but has independent working changes and checkout state. **All committed changes from any worktree are
14-
visible to all other worktrees including the main repository.**
11+
- **[SSH Workspaces](./ssh.md)**: Regular git clones on a remote server accessed via SSH. These are completely independent repositories stored on the remote machine.
1512

16-
It's important to note that a **worktree is not locked to a branch**. The agent can switch to new
17-
branches, enter a detached HEAD state, etc. When you create a workspace, the agent will
18-
begin at the selected branch but may switch freely in the course of the session. **We empower users to define their agent's branching strategy in AGENTS.md**
13+
## Choosing a Backend
1914

20-
## Reviewing code
15+
The workspace backend is selected when you create a workspace:
2116

22-
Here are a few practical approaches to reviewing changes from workspaces,
23-
depending on how much you want your agent to interact with `git`:
17+
- **Local**: Best for fast iteration, local testing, and when you want to leverage your local machine's resources
18+
- **SSH**: Ideal for heavy workloads, long-running tasks, or when you need access to remote infrastructure
19+
20+
## Key Concepts
21+
22+
- **Isolation**: Each workspace has independent working changes and Git state
23+
- **Branch flexibility**: Workspaces can switch branches, enter detached HEAD state, or create new branches as needed
24+
- **Parallel execution**: Run multiple workspaces simultaneously on different tasks
25+
- **Shared commits**: Local workspaces (using worktrees) share commits with the main repository immediately
26+
27+
## Reviewing Code
28+
29+
Here are a few practical approaches to reviewing changes from workspaces, depending on how much you want your agent to interact with `git`:
2430

2531
- **Agent codes, commits, and pushes**: Ask agent to submit a PR and review changes in your git Web UI (GitHub, GitLab, etc.)
2632
- Also see: [Agentic Git Identity](./agentic-git-identity.md)
2733
- This is the preferred approach for `cmux` development but requires additional care with repository security.
2834
- **Agent codes and commits**: Review changes from the main repository via `git diff <workspace-branch>`, push changes when deemed acceptable.
29-
- **Agent codes**: enter worktree (click Terminal icon in workspace top bar), run `git add -p` and progressively accept changes into a commit.
30-
31-
## Reviewing functionality
32-
33-
Some changes (esp. UI ones) require the Human to determine acceptability. An effective approach
34-
for this is:
35-
36-
1. Ask agent to commit WIP when its ready for Human review
37-
1. Human, in main repository, checks out the workspace branch in a detached HEAD state: `git checkout --detach <workspace-branch>`
35+
- **Agent codes**: Enter worktree (click Terminal icon in workspace top bar), run `git add -p` and progressively accept changes into a commit.
3836

39-
Note: this workflow uses the detached HEAD state because the branch is already
40-
checked out in the workspace and you cannot check out the same branch multiple times
41-
across worktrees.
37+
## Reviewing Functionality
4238

43-
If you want faster iteration in between commits, you can hop into the worktree directory and run a
44-
dev server (e.g. `bun dev`) there directly and observe the agent's work in real-time.
39+
Some changes (especially UI ones) require the Human to determine acceptability. An effective approach for this is:
4540

46-
## Filesystem Layout
41+
1. Ask agent to commit WIP when it's ready for Human review
42+
2. Human, in main repository, checks out the workspace branch in a detached HEAD state: `git checkout --detach <workspace-branch>` (for local workspaces)
4743

48-
Local workspaces are stored in `~/.cmux/src/<project-name>/<workspace-name>`.
44+
**Note**: For local workspaces, this workflow uses the detached HEAD state because the branch is already checked out in the workspace and you cannot check out the same branch multiple times across worktrees.
4945

50-
SSH workspaces are stored on the remote machine at `~/workspace/<project-name>/<workspace-name>` (or your configured remote path).
46+
If you want faster iteration in between commits, you can hop into the workspace directory and run a dev server (e.g. `bun dev`) there directly and observe the agent's work in real-time.
5147

52-
Example layout:
48+
---
5349

54-
```
55-
~/.cmux/src/
56-
cmux-main/
57-
improved-auth-ux/
58-
fix-ci-flakes/
59-
```
50+
See the specific workspace type pages for detailed setup and usage instructions.

‎flake.nix‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,11 @@
130130
bash
131131
nixfmt-rfc-style
132132

133+
# Documentation
134+
mdbook
135+
mdbook-mermaid
136+
mdbook-linkcheck
137+
133138
# Terminal bench
134139
uv
135140
asciinema

‎scripts/docs.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,5 @@ if [ ! -f "docs/mermaid-init.js" ] || [ ! -f "docs/mermaid.min.js" ]; then
88
cd ..
99
fi
1010

11-
# Serve the docs
12-
cd docs && mdbook serve --open
11+
# Serve the docs (bind to all hosts for remote access)
12+
cd docs && mdbook serve --hostname 0.0.0.0 --open

0 commit comments

Comments
 (0)