Workshop: Building Research Websites with Claude Code

Claude Code can do most of the mechanical work of a research website: scaffolding the site, drafting pages, building tables and diagrams, and fixing build errors. This workshop shows how to start one in about an hour, and how to keep its content trustworthy afterwards.

Setup instructions last checked against the Claude Code, Astro and Vercel documentation on 15 October 2026.

Before the workshop

Install these before you arrive:

1. Node.js 22.12 or later. Current Astro releases require it. Get the LTS version from nodejs.org and check with node --version.
2. Claude Code, using the native installer (details below). Then run claude once to log in. Claude Code needs a Pro, Max, Team, Enterprise or Console account; the free Claude plan does not include it.
3. A terminal you’re comfortable with, such as iTerm2, the VS Code terminal or Windows Terminal.

Can’t install software on your laptop? The Claude Code on the Web guide covers doing the whole workshop in the browser, with no local Node.js or terminal.

Keep a chat open for questions

Keep an LLM chat open alongside the workshop, such as Claude.ai, ChatGPT or Gemini. Use it for side questions: “What does this terminal error mean?”, “Help me split this topic into sections”, “What does npm run dev do?” This is separate from Claude Code, which edits your files.

---

About this workshop

Organized by the Quantified Uncertainty Research Institute (QURI). For background, see the LongTermWiki pages on AI-assisted knowledge management, LongTermWiki itself and QURI.

A live session has three parts: a short presentation on how Claude Code builds research websites and which topics suit the approach, a hands-on session where you start your own site, and a closing round to share progress and problems. The slides are online. A version of this workshop was given at MOX SF in January 2026.

---

What we’re building

You’ll start a research mini-website: a structured knowledge base, mini-textbook or wiki on a topic in prioritization research, EA cause areas, or a related field. A finished site takes longer, but an hour gets you a solid start.

1. You choose the topic, the structure and the editorial direction.
2. Claude Code does the heavy lifting: scaffolding, drafting, creating pages, fixing build errors.
3. You review, edit and iterate.

What is Claude Code?

Claude Code is Anthropic’s agentic coding tool. It reads and edits the files in your project, runs commands and searches the web, all from a conversation: you describe what you want, and Claude does it. It runs in the terminal, in VS Code and JetBrains IDEs, in the Claude desktop app, and in the browser at claude.ai/code. This walkthrough assumes the terminal; the web guide covers the browser.

Demo projects

All of these were built mainly with Claude Code:

Project	What it is
LongTermWiki	AI safety knowledge base: risks, interventions, organizations, key uncertainties. Has a YAML data layer and custom components.
Delegation Risk	Mini-textbook with theory, case studies and interactive tools
Evaluation Engineering	Small book with numbered chapters on systems that produce evaluations at scale
Robust Reasoning Processes	Working notes on reasoning processes that resist corruption

LongTermWiki’s source is at github.com/quantified-uncertainty/longterm-wiki. It took months of iteration, but its basic structure was scaffolded in a single session. The other three live in the CAIRN repository, and this handbook describes how that repository works.

Rough time budget (hands-on session)

Phase	Time	What you’re doing
Setup & scaffold	~10 min	Create the project, start the dev server, open Claude Code
Initial structure	~10 min	Create the page structure with one large prompt
Content	~35 min	Expand pages, iterate on content, add detail
Polish	~10 min	Cross-references, fixes, appearance
Wrap-up	~5 min	Commit, discuss deployment

---

Installing Claude Code

The native installer is the recommended method. It needs no Node.js and updates itself.

macOS, Linux, WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell)

irm https://claude.ai/install.ps1 | iex

You don’t need to run it as Administrator. Installing Git for Windows is recommended, because it gives Claude Code a Bash shell; without it, Claude Code uses PowerShell.

Homebrew

brew install --cask claude-code

Homebrew installs don’t update themselves. Run brew upgrade claude-code now and then.

WinGet

winget install Anthropic.ClaudeCode

WinGet installs don’t update themselves either. Run winget upgrade Anthropic.ClaudeCode now and then.

Open a new terminal, then run claude --version to check the install and claude to log in through your browser. An npm package also exists (npm install -g @anthropic-ai/claude-code, Node.js 22 or later). If you use it, never run it with sudo; Anthropic’s docs warn this causes permission and security problems. See the setup docs for other platforms and for install troubleshooting.

Cost: read before the workshop

A Claude subscription is simplest. Pro ($20/month billed monthly) and Max (from $100/month) include Claude Code, so there is no surprise bill (prices as of October 2026; see claude.com/pricing). Subscriptions have usage limits per session window and per week. If you hit one, Claude Code tells you when it resets, and /usage shows how much you have used. Max has higher limits than Pro.

Using the API instead? Sign in with a Claude Console account and set a spend limit before the workshop. Cost depends on the model and on how long your sessions run; /usage shows an estimate for the current session.

Key resources

• Claude Code docs, including the quickstart and best practices
• github.com/anthropics/claude-code
• VS Code extension and desktop app, if you’d rather not work in a terminal

---

Terminal setup: the multi-window workflow

Run several terminal windows at once:

Window	Purpose	What’s running
Window 1 (large)	Claude Code	claude
Window 2	Dev server	npm run dev, a live preview of your site
Window 3	General terminal	Git commands, file browsing, manual edits

Keep your browser open at http://localhost:4321. It reloads as Claude changes files, so you can look at the result, then go back and tell Claude what to fix.

iTerm2 (macOS)

• Cmd+D: split pane vertically
• Cmd+Shift+D: split pane horizontally
• Cmd+[ / Cmd+]: switch between panes

A good layout is Claude Code in a tall left pane, the dev server top right and a general terminal bottom right.

VS Code

Split the built-in terminal with Cmd+\ (Ctrl+Shift+5 on Windows/Linux), or use the Claude Code extension with Claude in the sidebar and terminals below.

Windows Terminal

• Alt+Shift+D: duplicate pane
• Alt+Shift+Plus: split vertically
• Alt+Shift+Minus: split horizontally
• Alt+Arrow: switch panes

---

Choosing a framework

Framework	Best for	Scaffold command
Astro + Starlight	Wikis and research docs (our choice)	npm create astro@latest -- --template starlight
Docusaurus	Docs and blogs	npx create-docusaurus@latest my-wiki classic
VitePress	Vue-based docs	npx vitepress init
MkDocs Material	Python-based docs	pip install mkdocs-material && mkdocs new .

We use Starlight because pages are plain Markdown/MDX files, which Claude Code edits directly. Search, sidebar, dark mode and mobile layout work out of the box, the output is a fast static site, and React components are available when you need interactivity. The Claude Code workflow is the same for any of these frameworks.

Non-code alternatives

Tool	AI integration	Publishing	Best for
Obsidian + Quartz	AI plugins, local-first	Quartz builds a static site from your vault	Personal research wikis, interlinked notes
Notion	Built-in Notion AI	Notion Sites or public sharing	Team wikis, collaborative docs
Google NotebookLM	Built in, grounded in your sources	Export only	Q&A over a fixed set of documents

These are quicker to start if you don’t want to manage code, but harder to customize. The code approach suits a site you want full control over, with custom components, that will keep growing.

---

Workshop walkthrough

1. Pick your research topic

   Choose a topic in prioritization research, EA cause areas, or a related field that you know something about. For the hands-on session, aim for 3–5 sections of 2–4 pages each.

   Examples of a good scope:

   • “Key uncertainties in AI governance” (Policy Approaches, Technical Standards, International Coordination, Key Debates)
   • “Guide to the biosecurity funding landscape” (Major Funders, Funding Gaps, Grant Mechanisms, Emerging Priorities)
   • “S-risk research overview” (Definitions & Scope, Key Scenarios, Interventions, Open Questions)
   • “Forecasting methods for cause prioritization” (Base Rates, Expert Elicitation, Prediction Markets, Model Comparison)
   • “Animal welfare intervention cost-effectiveness” (Factory Farming, Wild Animal Welfare, Measurement Challenges, Key Organizations)

   Too broad: “Everything about existential risk”. Too narrow: “One specific Metaculus question”, which is a page, not a wiki.

   What makes a topic well-suited?

   • Natural decomposition. If you can sketch 3–5 groups of 2–4 related subtopics, it fits.
   • Existing literature to synthesize. Claude draws on published material, so well-documented topics come out much better than unpublished research.
   • Value from organization, not original analysis. The format is good at structuring and connecting existing knowledge. Claude is unreliable at novel calculations and original arguments.
   • You can check the output. Claude will invent facts and citations, and present contested claims as consensus. Your domain knowledge is the filter.

   Avoid topics that need precise calculation (use a spreadsheet), topics whose sources are mostly paywalled, and topics where you would be generating new research claims rather than synthesizing existing ones.

2. Scaffold the project

   Either option works for the workshop.

   Vanilla Starlight

   npm create astro@latest -- --template starlight my-wiki

   Answer Yes to “Install dependencies?” and “Initialize a new git repository?”, then cd my-wiki.

   Windows users: avoid paths with spaces (e.g. C:\Users\John Smith\...). Use a short path such as C:\projects\my-wiki.

   QURI starter

   Our starter adds Mermaid diagrams, KaTeX maths, React components and a CLAUDE.md:

   npx degit quantified-uncertainty/cairn/starters/research-wiki my-wiki
   cd my-wiki
   npm install
   git init

   It includes example pages showing each feature. Delete them once you have your own content.

   Checkpoint: a my-wiki/ folder containing src/content/docs/, astro.config.mjs and package.json.

3. Start the dev server (Window 2)

   npm run dev

   Open http://localhost:4321. The starter shows a “My Research Wiki” splash page; vanilla Starlight shows “Welcome to Starlight”. If port 4321 is taken, run npm run dev -- --port 4322 and open that port instead.

4. Start Claude Code (Window 1)

   claude

   Permission modes

   The permission mode decides what Claude may do without asking you. Where it is available, recent versions start in Auto, in which a second model reviews each action instead of you. Shift+Tab cycles through the modes:

   • Manual: Claude asks before editing files or running commands. Safest, but slow.
   • Accept edits: file edits and simple file commands go through; other commands still ask.
   • Plan: Claude reads and proposes a plan, and edits nothing until you approve it. Useful before the big structure prompt in the next step.
   • Auto: everything runs, with background safety checks.

   claude --dangerously-skip-permissions skips all checks. Anthropic’s docs recommend it only inside an isolated container or VM.

5. Create the whole page structure in one prompt

   Give Claude one detailed prompt that creates the skeleton of the wiki. Shift+Enter inserts a newline in most terminals; if it doesn’t in yours, type \ then Enter, or run /terminal-setup once. Enter submits.

   Here is a worked example you can adapt:

   Full example (AI governance)

   I'm building a research wiki about key uncertainties in
   AI governance. Create the following structure:
   
   Sections:
   1. Policy Approaches — pages: compute-governance,
      licensing-regimes, liability-frameworks,
      international-treaties
   2. Technical Standards — pages: model-evaluations,
      safety-benchmarks, deployment-standards,
      red-teaming-requirements
   3. International Coordination — pages:
      us-china-dynamics, eu-ai-act, global-governance-gaps,
      multilateral-proposals
   4. Key Debates — pages: open-vs-closed-source,
      pace-of-regulation, voluntary-vs-mandatory,
      frontier-vs-broad-regulation
   
   For each page:
   - Create an MDX file in src/content/docs/ with
     appropriate subdirectories
   - Include frontmatter with title and description
   - Write a 2-3 paragraph introduction covering the
     current state of debate
   - Add 3-4 section headers outlining what the page
     will cover (e.g., Background, Key Arguments,
     Open Questions, Further Reading)
   - Include at least one Markdown table where relevant
     (e.g., comparing policy proposals, listing key
     actors, summarizing positions)
   
   Also:
   - Remove the default/example pages that came with
     the template (e.g., the example/ directory)
   - Update astro.config.mjs to use autogenerate for
     each section directory, like:
     { label: 'Policy Approaches',
       autogenerate: { directory: 'policy-approaches' } }
   - Update the site title to
     "AI Governance: Key Uncertainties"
   - Use .mdx extension for all files.

   Template: research wiki

   I'm building a research wiki about [TOPIC]. Create
   the following structure:
   
   Sections:
   1. [Section 1] — pages: [page-a], [page-b], [page-c]
   2. [Section 2] — pages: [page-d], [page-e]
   3. [Section 3] — pages: [page-f], [page-g], [page-h]
   4. [Section 4] — pages: [page-i], [page-j]
   
   For each page:
   - Create an MDX file in src/content/docs/ with
     appropriate subdirectories
   - Include frontmatter with title and description
   - Write a 2-3 paragraph introduction
   - Add section headers for what the page will cover
   - Include at least one Markdown table where relevant
   
   Also:
   - Remove the default/example pages that came with
     the template
   - Update astro.config.mjs to use autogenerate for
     each section directory
   - Update the site title to "[YOUR WIKI NAME]"
   - Use .mdx extension for all files.

   Template: mini-textbook

   I'm building a mini-textbook about [TOPIC]. Create
   the following chapter structure:
   
   Chapters:
   1. [Chapter 1 Title] — 3 pages covering [subtopics]
   2. [Chapter 2 Title] — 3 pages covering [subtopics]
   3. [Chapter 3 Title] — 2 pages covering [subtopics]
   4. [Chapter 4 Title] — 2 pages covering [subtopics]
   
   Each chapter should have an index.mdx overview page
   plus individual topic pages. Write in a clear,
   analytical tone aimed at researchers and policy
   professionals.
   
   For each page, include:
   - A clear introduction explaining why this matters
   - Key concepts with explanations and evidence
   - At least one concrete example or case study
   - An "Open Questions" section where relevant
   
   Also:
   - Remove the default/example pages that came with
     the template
   - Update astro.config.mjs to use autogenerate for
     each chapter directory
   - Update the site title to "[YOUR TEXTBOOK NAME]"
   - Use .mdx extension for all files.

   Checkpoint: after a few minutes, the browser shows every section in the sidebar, with stub pages that have introductions.

6. Check the browser and start expanding

   Pick a page and fill it in:

   Expand the page at src/content/docs/policy-approaches/compute-governance.mdx
   with detailed content. Include the key proposals (chip export controls, compute
   thresholds, KYC for cloud), a table comparing approaches by feasibility and
   effectiveness, and a section on open questions.

   Or react to what you see:

   The intro on the licensing-regimes page is too vague. Add specific examples
   of existing licensing proposals (EU AI Act tiers, proposed US frameworks),
   a comparison table, and the key arguments for and against.

   Claude Code can search the web, which matters for research content: “Search for recent papers on [topic] and add a literature summary to this page.” To draft several pages at once, ask it to use subagents: “Draft these four pages in parallel using subagents.”

   Quality comes from iterating in layers. The first prompt gives a scaffold; the next two or three make it good:

   Turn	You say	What improves
   1	”Create a page about compute governance”	A generic overview
   2	”Too surface-level. Add the specific proposals: chip export controls (Oct 2022 BIS rules), compute thresholds (10^25 FLOP), KYC for cloud. Include a table comparing them by feasibility and effectiveness.”	Specific proposals and a structured comparison
   3	”The Open Questions section is weak. Add: (1) Does compute governance become less relevant as algorithmic efficiency improves? (2) How do you enforce thresholds when distillation makes smaller models more capable?”	The questions researchers actually care about
   4	”Add cross-references to the licensing-regimes and international-coordination pages.”	A connected knowledge base instead of isolated pages

   The most common mistake is creating 15 shallow pages instead of making 5 good ones.

   Watch for generic output and invented sources

   After the scaffold, every page tends to sound the same. Give Claude a specific voice: “Write in the style of a GiveWell cost-effectiveness analysis” or “Match the tone of 80,000 Hours career profiles.” Claude will also confidently link to papers and URLs that don’t exist; ask it to search the web before writing factual sections.

7. If you’re stuck, try these prompts

   What you want	Prompt
   Deepen a page	”Expand [page] with specific evidence, key arguments from the literature, and quantitative estimates where available”
   Add structure	”Add a comparison table to [page] covering the major positions/proposals/interventions”
   Connect pages	”Add cross-references between related pages — link from each page to relevant others”
   Sharpen analysis	”Rewrite the intro of [page] to be more analytically precise. State the key cruxes upfront.”
   Add a diagram	”Add a Mermaid diagram to [page] showing the causal chain from [intervention] to [outcome]“
   Create a page	”Create a new page at src/content/docs/[section]/[name].mdx about [topic]“
   Fix something broken	”The dev server is showing an error. Read the terminal output and fix whatever is wrong.”
   Research and write	”Search the web for [topic], then update [page] with current information and citations”
   Add a literature review	”Add a ‘Key Papers’ section to [page] summarizing the 3-5 most important papers on this topic”
   Create an overview	”Create an index page at src/content/docs/index.mdx that summarizes the research area and links to all sections”

8. Customize the appearance (about 2 minutes)

   Customize this site: change the title to "[Your Research Topic]",
   add a tagline "[your tagline]", and change the accent color
   to [blue/green/purple/orange]. Also update the hero section
   on the landing page.

   Starlight supports theme customization of colours, fonts and CSS.

9. Save your progress (Window 3)

   git add -A && git commit -m "workshop: initial research wiki"

   Commit after the scaffold, after expanding content and before changing the appearance. git diff shows what changed, and git restore <file> reverts one file. Inside Claude Code, Esc Esc (or /rewind) rolls back Claude’s own edits and the conversation to an earlier point.

   Checkpoint: a multi-section research site with several fleshed-out pages, cross-references and your own branding.

---

Claude Code tips

Essential commands

Command	What it does
claude	Start Claude Code in the current directory
claude "prompt here"	Start with an initial prompt
claude --continue	Reopen the most recent conversation in this directory
claude --resume	Pick an earlier conversation to reopen
Shift+Enter	New line (or \ then Enter; /terminal-setup fixes Shift+Enter in some terminals)
Shift+Tab	Cycle permission modes: Manual, Accept edits, Plan, Auto
Esc	Stop Claude mid-response, keeping the work so far
Esc Esc / /rewind	Restore code and conversation to an earlier checkpoint
/clear	Start a fresh conversation with empty context
/compact	Summarize the conversation so far to free up context
/context	Show how full the context window is
/init	Generate a CLAUDE.md for the project
Ctrl+D (twice)	Exit

Situation	Use
Claude is confused or keeps repeating a mistake	/clear, then restate the task. Put lasting corrections in CLAUDE.md.
A long session is losing track of earlier instructions	/compact. Claude Code also compacts automatically as the context fills up.
Switching to an unrelated task	/clear or a new claude session

The docs list everything else; feature names change often, so check there rather than relying on this table.

Working effectively

Give feedback, not just instructions. Look at the result in the browser and say what’s wrong:

“The analysis is too surface-level. Add specific numbers, cite key papers, and state the key uncertainties.”

Name specific files:

“Read src/content/docs/key-debates/open-vs-closed.mdx and improve it — the arguments section needs steel-manned versions of both sides.”

When Claude asks about something you don’t care about, say “your call” to keep moving.

If Claude creates files in the wrong place (e.g. docs/ instead of src/content/docs/), give exact paths in the prompt and add the convention to CLAUDE.md.

---

CLAUDE.md: teaching Claude about your project

Claude Code reads CLAUDE.md in the project root at the start of every session. It is a standing brief: the project’s structure, commands and conventions. The QURI starter includes one. Otherwise, run /init to generate one, or ask:

Create a CLAUDE.md for this project. Include the dev command,
build command, project structure, content conventions, and the
sidebar autogenerate pattern we're using.

A minimal hand-written version:

# My Research Wiki

## Commands
- `npm run dev` — Start dev server at localhost:4321
- `npm run build` — Build for production

## Structure
- `src/content/docs/` — All wiki pages (MDX format)
- `astro.config.mjs` — Site config and sidebar
- `public/` — Static assets (images, etc.)

## Conventions
- Use .mdx extension for all pages
- Use Markdown tables for comparisons
- Keep pages focused on one topic each
- Escape $ signs in MDX: \$100
- Use autogenerate for sidebar sections in astro.config.mjs
- Put images in public/images/ and reference as /images/name.png

## Content Style
- Analytical and evidence-based tone
- Cite sources where possible
- Include "Open Questions" sections
- Use tables for comparing positions/proposals

Without CLAUDE.md, every session rediscovers your project from scratch. With one, Claude knows your commands and conventions from the first message, which matters once you work across many sessions.

---

Prompting for research content

What works

Be specific about structure:

“Create a page about X with: a background section, a ‘Key Arguments’ section with the major positions, a comparison table, an ‘Open Questions’ section, and a ‘Further Reading’ section.”

Use an existing page as a template:

“Look at src/content/docs/section-1/page-a.mdx and create a similar-style page for [new topic].”

Use web search for current data:

“Research the latest developments in [topic] and write a page with current figures, recent papers, and links to sources.”

Iterate in layers: get the structure right, then fill in detail.

“The section on X is too vague. Add specific estimates, cite Ord/Cotra/Davidson/etc., and state the key cruxes.”

What to watch for

• Invented facts and citations. Check numbers, dates, quotes and paper citations. Never trust a URL Claude produces without opening it; ask it to search for real links instead.
• Plausible but wrong numbers. Check any specific dollar figure, percentage or date.
• Lopsided “Key Arguments” sections. Claude tends to strengthen mainstream views and weaken minority ones. Check that each side is stated as its proponents would state it.
• US/Western-centric content. Ask for other perspectives if the topic needs them.
• MDX quirks. <, { and $ in text need escaping. If the build breaks, paste the error to Claude.
• Quantity over quality. Ten well-researched pages beat thirty shallow ones.

Reviewing content

Scaffold broadly, then review narrowly. Generate the full structure in the first 20 minutes, then spend the rest of the time improving 3–5 pages.

For pages you want to trust:

1. Spot-check citations. If Claude names a paper, organization or statistic, confirm it exists: “Search the web to verify whether [claim] is accurate.”
2. Ask for a self-audit. “Read this page and list any claims you’re less than 80% confident are correct.” This is a useful first pass, not a substitute for checking sources.
3. Ask what’s missing. “What important perspectives or counterarguments are missing from this page?”
4. Look for false precision. Exact percentages, confident timelines and precise costs with no source are typical of LLM drafts. Source them or soften them.

For a site you plan to publish, the Review Workflow page describes the heavier audit-and-verify process used on the CAIRN wikis.

---

Useful patterns

Auto-generated sidebar

Instead of listing every page in astro.config.mjs, generate sidebar sections from directories:

sidebar: [
  { label: 'Policy Approaches', autogenerate: { directory: 'policy-approaches' } },
  { label: 'Key Debates', autogenerate: { directory: 'key-debates' } },
  { label: 'Open Questions', autogenerate: { directory: 'open-questions' } },
]

Pages within a section are sorted alphabetically by filename. To set the order, add sidebar: { order: 1 } to each page’s frontmatter. Numeric filename prefixes such as 01-intro.mdx also sort, but the number ends up in the page’s URL. For a book with numbered chapters, an explicit sidebar list is clearer; two of the CAIRN wikis use one (see Adding a Wiki).

Images

Put images in public/ and reference them from the site root:

![Description of the image](/images/my-diagram.png)

Tables over paragraphs

For comparisons, positions or structured data, a table is usually clearer than prose:

| Approach | Feasibility | Effectiveness | Key Proponents |
|----------|-------------|---------------|----------------|
| Compute governance | High | Medium | Brundage, Heim |
| Licensing regimes | Medium | Medium-High | EU, NIST |
| Voluntary commitments | High | Low | Industry |

Cross-references

Links between pages are what make a wiki more than a set of essays:

See [the compute governance page](/policy-approaches/compute-governance/) for details.

---

Deployment (after the workshop)

Make sure npm run build succeeds locally first; a hosting platform fails on the same errors.

Vercel (recommended)

1. Push the repository to GitHub.
2. Sign up at vercel.com with GitHub (there is a free tier).
3. Open vercel.com/new and select the repository. Vercel detects Astro; click Deploy.
4. The site is live at your-project.vercel.app.

After that, each push to main updates the live site, and each other branch or pull request gets its own preview URL.

Netlify

1. Push the repository to GitHub.
2. Sign in at netlify.com with GitHub.
3. Add new project → Import an existing project, then select the repository.
4. Build command npm run build, publish directory dist/.
5. Deploy. The URL looks like your-site.netlify.app.

Cloudflare Pages

1. Push the repository to GitHub.
2. Go to pages.cloudflare.com.
3. Connect the repository, with build command npm run build and output directory dist/.

If you’re using Claude Code on the web, see that guide’s working loop, which uses Vercel preview deployments.

---

After the workshop

• Deploy it. A live URL is motivating.
• Run /init if you don’t have a CLAUDE.md yet.
• Improve before you expand. Make existing pages good before adding more.
• Learn Starlight. The docs cover theming, components and more.
• Turn repeated patterns into components. If you keep writing the same kind of box or table, ask Claude to make it a reusable MDX component.

What scaled projects look like

LongTermWiki eventually added content validators (link checking, quality scoring), a YAML data layer with cross-referenced entities, custom React components and automated improvement pipelines. The CAIRN wikis use a lighter setup: an explicit sidebar, generated llms.txt files and a link checker that CI runs after every build (see Build & Tooling). You need none of this to start.

---

Quick reference links

Resource	URL
Workshop slides	Google Slides
QURI	quantifieduncertainty.org
Claude Code docs	code.claude.com/docs/en/overview
Claude Code setup	code.claude.com/docs/en/setup
Claude Code best practices	code.claude.com/docs/en/best-practices
Starlight docs	starlight.astro.build
Starlight frontmatter reference	starlight.astro.build/reference/frontmatter
Astro docs	docs.astro.build
MDX docs	mdxjs.com
QURI starter	npx degit quantified-uncertainty/cairn/starters/research-wiki my-wiki
CAIRN source	github.com/quantified-uncertainty/cairn
LongTermWiki source	github.com/quantified-uncertainty/longterm-wiki

---

Troubleshooting

Setup and installation

Node.js too old or missing

• Run node --version. You need 22.12 or later. Install the LTS version from nodejs.org.
• With nvm: nvm install --lts && nvm use --lts.

claude: command not found after installing

• Open a new terminal window first. If it still isn’t found, the install directory isn’t on your PATH; see the install troubleshooting docs.

Permission errors (EACCES) when installing

• These come from a global npm install. Use the native installer instead. Don’t use sudo npm install -g.

Login fails

• Run claude auth logout, then claude again.
• Check that a corporate VPN or proxy isn’t blocking Anthropic’s servers.
• If the browser doesn’t open, copy the login URL from the terminal into a browser.

npm create astro or npx degit hangs

• Usually the network, especially on crowded workshop Wi-Fi. Run npm cache clean --force and retry, or git clone the starter instead.

Port 4321 already in use

• Another process, perhaps an old dev server, holds the port. Stop it (lsof -i :4321, then kill <PID> on macOS/Linux), or run npm run dev -- --port 4322.

Build and content errors

Build fails after creating pages

• Usually invalid frontmatter YAML or unescaped special characters ($, <, {). Paste the error to Claude: “The build failed with this error: [paste]. Fix it.”

Frontmatter YAML errors (bad indentation and similar)

• Usually a colon in an unquoted title. Quote it: title: "AI: Key Questions".

Build fails with a schema error about title

• Every page needs a title in its frontmatter: --- / title: "Page Title" / ---.

MDX import or syntax errors

• Keep all import lines together directly after the frontmatter, outside any JSX, and check that each imported component is spelled the same where it’s used. Otherwise, paste the error to Claude.

Claude writes .md files instead of .mdx

• Plain Markdown works for pages without components. If you want .mdx throughout, say so in CLAUDE.md.

A component is used without being imported

• Ask Claude to add the import, e.g. import { Aside } from '@astrojs/starlight/components'; at the top of the file.

Mermaid diagrams or maths don’t render

• Vanilla Starlight doesn’t include them. Use the QURI starter, or ask Claude to “add Mermaid diagram and KaTeX math support to this Starlight project”.

Sidebar and navigation

New pages don’t appear in the sidebar

• With autogenerate, the directory in astro.config.mjs must match the folder name under src/content/docs/.
• If a whole section is missing, Claude probably didn’t add it to the config. Ask it to check.

Pages are in the wrong order

• Add sidebar: { order: 1 } (2, 3, …) to the pages’ frontmatter, or list the pages explicitly in the sidebar config.

Links between pages return 404

• URLs follow the file layout: src/content/docs/section/page.mdx becomes /section/page/, with a trailing slash. Folder and file names are case-sensitive.

Images don’t show

• public/images/foo.png is referenced as /images/foo.png, without public/.

Claude Code sessions

Claude seems confused or repetitive

• Use /clear and restate the task, and make sure you started claude from the project root, not a subdirectory.

Claude keeps making the same mistake

• Add the correction to CLAUDE.md, e.g. “Always escape $ signs in MDX files”.

Claude edited the wrong file

• Esc Esc or /rewind restores an earlier checkpoint. git diff shows what changed, and git restore <file> reverts a file. This is why committing after each phase matters.

Terminal crashed or disconnected

• Run claude --continue. Your files are on disk regardless of the session.

“You’ve hit your session limit” or “weekly limit”

• A subscription usage limit. The message says when it resets; /usage shows where you stand. Max plans have higher limits.

Dev server

Dev server crashed

• Restart it with npm run dev. The usual cause is an MDX syntax error; paste the terminal error to Claude.

Hot reload stopped working

• Restart the dev server (Ctrl+C, then npm run dev) and hard-refresh the browser (Cmd+Shift+R / Ctrl+Shift+R).

A page looks garbled

• Usually unescaped characters or an unclosed tag in the MDX. Ask Claude: “The page at [path] looks broken in the browser. Read it and fix the MDX syntax.”

Content quality

All pages sound the same

• Give Claude a voice (“Write in the style of a GiveWell cost-effectiveness analysis”) and vary the depth (“This is a major page, about 1500 words” vs. “a brief overview, 300 words at most”).

Claude invents organizations, papers or statistics

• Ask it to search before writing factual sections: “Search the web for real organizations working on X, then write this section.”

Claude won’t take a position

• “State which position has stronger evidence and why, while noting the key uncertainties.”

Tables are generic

• Give the exact columns: “Create a table with columns: Proposal, Lead Organization, Implementation Status, Estimated Cost, Key Criticism.”

Deployment

Build works locally but fails on Vercel or Netlify

• Usually a Node.js version mismatch. Set the Node version in the platform’s settings to match node --version, or add "engines": { "node": ">=22.12" } to package.json.

Every page 404s on the deployed site

• Check base in astro.config.mjs. At a domain root (the usual case on Vercel and Netlify), omit it or set it to '/'.

The site loads but styles or images are missing

• Usually the site is served from a subpath that base doesn’t match. base controls asset paths; site sets the canonical URL and sitemap and doesn’t affect them.