Add worktrees and Zed guides

content-collections.ts

@@ -1,10 +1,11 @@
 import { defineConfig } from '@content-collections/core';
 import { collection as authors } from './src/collections/authors/index.js';
+import { collection as guides } from './src/collections/guides/index.js';
 import { collection as notes } from './src/collections/notes/index.js';
 import { collection as posts } from './src/collections/posts/index.js';
 import { collection as tags } from './src/collections/tags/index.js';
 import { collection as videos } from './src/collections/videos/index.js';
 
 export default defineConfig({
-	content: [authors, notes, posts, tags, videos]
+	content: [authors, guides, notes, posts, tags, videos]
 });

src/collections/guides/index.ts

@@ -0,0 +1,20 @@
+import { defineCollection } from '@content-collections/core';
+import { docMetaSchema } from '@maiertech/sveltekit-helpers';
+
+export const collection = defineCollection({
+	name: 'guides',
+	directory: 'src/routes/guides',
+	include: '**/*.md',
+	parser: 'frontmatter-only',
+	schema: docMetaSchema,
+	transform: async (guideMeta) => {
+		// Derive path from `_meta.directory`: slug-name → /guides/slug-name.
+		const slug = guideMeta._meta.directory.split('/').pop();
+		const path = `/guides/${slug}`;
+
+		return {
+			...guideMeta,
+			path
+		};
+	}
+});

src/lib/server/collections/guides.ts

@@ -0,0 +1,6 @@
+import { allGuides } from 'content-collections';
+
+// Sort alphabetically by title.
+export const sorted = allGuides.toSorted((a, b) => {
+	return a.title.localeCompare(b.title);
+});

src/routes/guides/+layout.server.ts

@@ -0,0 +1,34 @@
+import { ORIGIN } from '$env/static/private';
+import { sorted as guides } from '$lib/server/collections/guides.js';
+import { latest as latestVideos } from '$lib/server/collections/videos.js';
+import { error } from '@sveltejs/kit';
+import type { LayoutServerLoad } from './$types';
+
+export const prerender = true;
+
+export const load: LayoutServerLoad = async ({ url }) => {
+	const index = guides.findIndex((guide) => guide.path === url.pathname);
+
+	if (index === -1) {
+		error(404, 'Guide not found.');
+	}
+
+	const guide = guides[index];
+	const prev = index > 0 ? guides[index - 1] : undefined;
+	const next = index < guides.length - 1 ? guides[index + 1] : undefined;
+
+	const recommendedVideos = latestVideos.slice(0, 3);
+
+	return {
+		origin: ORIGIN,
+		guide,
+		prev,
+		next,
+		recommendedVideos,
+		seo: {
+			title: guide.title,
+			description: guide.description,
+			ogImageUrl: guide.ogImageUrl
+		}
+	};
+};

src/routes/guides/+layout.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+	import { Pager, VideoList } from '$lib/components';
+	import { Clock } from '@lucide/svelte';
+	import { H1, SeoCanonicalUrl } from '@maiertech/sveltekit-helpers';
+	import type { LayoutProps } from './$types';
+
+	let { data, children }: LayoutProps = $props();
+</script>
+
+<SeoCanonicalUrl origin={data.origin} />
+
+<div class="flex flex-wrap gap-10">
+	<!-- `basis-0` to prevent `basis-auto`, which resolves to intrinsic width of longest para. -->
+	<div class="grow-999 basis-0 min-inline-3/5">
+		<H1 class="mb-12">{data.guide.title}</H1>
+		{@render children()}
+
+		<Pager prev={data.prev} next={data.next} class="mt-8" />
+	</div>
+
+	<aside class="flex grow basis-2xs flex-col gap-3">
+		<h2 class="flex items-center gap-2 text-ink-muted">
+			<Clock class="size-5" />
+			<span class="text-lg font-semibold">Latest videos</span>
+		</h2>
+		<VideoList values={data.recommendedVideos} level={3} />
+	</aside>
+</div>

src/routes/guides/warp/+page.md

@@ -0,0 +1,6 @@
+---
+title: Warp guide
+description: How to use Warp to for code reviews and agent orchestration.
+---
+
+Test

src/routes/guides/worktrees/+page.md

@@ -0,0 +1,52 @@
+---
+title: Worktrees guide
+description: Manual Git worktree management.
+---
+
+[Warp](/guides/warp) recognizes worktrees but does not support managing them. [Zed](/guides/zed)
+supports worktree management but does not allow you to co-locate worktrees with the main repository.
+
+## Create a worktree
+
+I want the worktree to be co-located with my cloned repository. If the cloned repository is
+`path/to/website`, the worktrees should reside in `path/to/website.worktrees`. This is a convention
+that VS Code's worktree implementation uses and that I like better than a central `worktrees`
+directory.
+
+Suppose you need a worktree for issue 1234. Run:
+
+```bash
+git worktree add -b i-1234 ../website.worktrees/w-1234
+```
+
+to create branch `i-1234` in worktree `w-1234`.
+
+Suppose you need a worktree to review pull request 1173, which uses branch `i-1172`. Run:
+
+```bash
+git worktree add ../website.worktrees/r-1173 i-1172
+```
+
+Using `r-1173` instead of `w-1173` as the worktree name makes it clear that this worktree is for
+code review.
+
+## Worktree management
+
+Run:
+
+```bash
+git worktree list
+```
+
+in the main repository or in any derived worktree to list all worktrees. The worktree location above
+is just a convention. Worktrees can be anywhere.
+
+Run:
+
+```bash
+git worktree remove ../website.worktrees/w-1234
+```
+
+to remove a worktree.
+
+Alternatively, Zed has great worktree management.

src/routes/guides/zed/+page.md

@@ -0,0 +1,66 @@
+---
+title: Zed guide
+description: How to use Zed for agentic coding.
+---
+
+## Shortcuts
+
+| Shortcut | Description         |
+| :------- | :------------------ |
+| `⌘ B`    | Toggle left dock.   |
+| `⌘ R`    | Toggle right dock.  |
+| `⌘ ⇧ E`  | Show project panel. |
+| `⌘ ⇧ G`  | Show Git panel.     |
+| `⌘ ⇧ B`  | Show outline panel. |
+| `⌘ ?`    | Show agent panel.   |
+| `⌃ ⇧ R`  | Review changes.     |
+| `@`      | Add to context.     |
+
+## Worktrees
+
+Workspace isolation is done with Git [worktrees](/guides/worktrees). You can manage worktrees with
+`git: worktree`. This works well except for the creation of new worktrees. Zed thinks that all
+worktrees it creates should be located in one central (but customizable) directory. And it does not
+support creating worktrees from existing branches.
+
+## Orchestration
+
+Use one worktree per window. The UI is not designed to run multiple agents in parallel. You can do
+this with one window per agent, but there is no good way to manage all the running agents.
+
+## Code reviews
+
+### Review files changed by agent
+
+You can look at uncommitted changes with `git: diff`. You can stage or restore changes one by one,
+but that is usually not what you want. When there are uncommitted changes made by an agent, you will
+see the **Review changes** button. Alternatively, you can use the keyboard shortcut to open this
+view. In this view, you can accept or reject the agent's changes one by one.
+
+When you do this is up to you. You might do a few iterations with the agent without looking at the
+code and then review, or you might review changes in every iteration. You can also copy all the
+diffs and add them to your agent's context, or rather another agent's context, and let the agent do
+a code review.
+
+### Pull request review
+
+One downside of Zed is that it does not yet have anything that matches
+[GitHub's pull requests extension](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github).
+You have to find a different workflow to do pull requests.
+
+Since you can't create a worktree from the pull request branch in Zed, you need to create a worktree
+for the review manually. With `git: branch diff`, you can create a diff between the default branch
+on origin and the branch you are on. It is currently not possible to diff against another branch,
+for example when you stack pull requests.
+
+You can create a diff and send it to your current agent for a first review.
+
+Two more useful features for exploring the pull request are the Git graph and the file history,
+which you can access for each file with a right-click.
+
+A big downside is that you cannot write line comments during a pull request review in Zed. You need
+to switch context to the Git provider's website.
+
+## Resolve merge conflicts
+
+Zed has built-in merge conflict resolution (not tested yet).