diff --git a/content-collections.ts b/content-collections.ts index df93a88a..9ce1a110 100644 --- a/content-collections.ts +++ b/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] }); diff --git a/src/collections/guides/index.ts b/src/collections/guides/index.ts new file mode 100644 index 00000000..b2032561 --- /dev/null +++ b/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 + }; + } +}); diff --git a/src/lib/server/collections/guides.ts b/src/lib/server/collections/guides.ts new file mode 100644 index 00000000..32a7858a --- /dev/null +++ b/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); +}); diff --git a/src/routes/guides/+layout.server.ts b/src/routes/guides/+layout.server.ts new file mode 100644 index 00000000..33add1ad --- /dev/null +++ b/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 + } + }; +}; diff --git a/src/routes/guides/+layout.svelte b/src/routes/guides/+layout.svelte new file mode 100644 index 00000000..1d1d557d --- /dev/null +++ b/src/routes/guides/+layout.svelte @@ -0,0 +1,28 @@ + + + + +
+ +
+

{data.guide.title}

+ {@render children()} + + +
+ + +
diff --git a/src/routes/guides/warp/+page.md b/src/routes/guides/warp/+page.md new file mode 100644 index 00000000..42f03da3 --- /dev/null +++ b/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 diff --git a/src/routes/guides/worktrees/+page.md b/src/routes/guides/worktrees/+page.md new file mode 100644 index 00000000..9f02ca83 --- /dev/null +++ b/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. diff --git a/src/routes/guides/zed/+page.md b/src/routes/guides/zed/+page.md new file mode 100644 index 00000000..607eb0b4 --- /dev/null +++ b/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).