Workshop: Building Research Websites with Claude Code

Claude Code can automate substantial portions of research documentation — generating mini-textbooks, interactive wikis, and structured knowledge bases from your research questions. This workshop teaches you how.

Install these before arriving so we can dive straight into building:

Node.js 18+ — nodejs.org (LTS version). Run node --version to check — if it says v16 or lower, you need to update.
Claude Code — npm install -g @anthropic-ai/claude-code, then run claude once to authenticate (cost info below). If you get EACCES permission errors on macOS/Linux, try sudo npm install -g @anthropic-ai/claude-code.
A terminal you’re comfortable with (iTerm2, VS Code, Windows Terminal, etc.)

Basic familiarity with Claude Code and the command line will be very useful.

Corporate or university laptop? If admin restrictions prevent installing Node.js or npm packages, use the web app instead.

Prefer to skip local setup? The Claude Code Web App lets you do everything in the browser — no terminal or Node.js required.

About This Workshop

Organized by the Quantified Uncertainty Research Institute (QURI). See also the LongTermWiki pages on AI-Assisted Knowledge Management, LongTermWiki itself, and QURI.

Format:

Opening presentation — How Claude Code builds research websites, key techniques, and what makes topics well-suited for this approach
Hands-on session — Begin your own research mini-website with guidance
Closing presentation — Share progress, discuss challenges, next steps

Slides: Google Slides

Upcoming event logistics (February 2026 — EAG SF)

Event: EAG SF 2026
Format: A shorter version of the full workshop

A previous version of this workshop was given at MOXSF in January 2026.

What We’re Building

You’ll start building a research mini-website — a structured knowledge base, mini-textbook, or wiki on a topic in prioritization research, EA cause areas, or related domains. Building a finished website would take longer, but this should be enough for a decent start.

The workflow:

You decide the research topic, structure, and editorial direction
Claude Code does the heavy lifting — scaffolding, writing drafts, creating pages, fixing build errors
You review, edit, and iterate

What is Claude Code?

Claude Code is an agentic coding tool that lets you use Claude AI to work directly on your codebase. It can read, write, and edit files in your project, run commands, and search the web — all through a conversational interface. You describe what you want, Claude executes it.

Claude Code is available as a CLI (terminal), a VS Code and JetBrains extension, and via the claude.ai/code web interface. This workshop walkthrough assumes the local CLI, but see the Claude Code Web App guide if you’d rather work entirely in the browser.

Think of it as pair programming with an AI that can actually touch your files.

Demo Projects

These were all built primarily with Claude Code:

Project	Description	Scale
LongTermWiki	Comprehensive AI safety knowledge navigator — risks, interventions, organizations, key uncertainties	~640 pages, YAML data layer, custom components
Delegation Risk	Structured mini-textbook with theory, case studies, and interactive tools	~100 pages

The source for LongTermWiki is at github.com/quantified-uncertainty/longterm-wiki (standalone repo) and also within the cairn monorepo. LongTermWiki took months of iterative work, but the basic structure was scaffolded in a single session.

Rough Time Budget (Hands-on Session)

Phase	Time	What You’re Doing
Setup & scaffold	~10 min	Create project, start dev server, open Claude Code
Initial structure	~10 min	Create page structure with one big prompt
Content creation	~35 min	Expand pages, iterate on content, add detail
Polish & extras	~10 min	Cross-references, fix issues, customize appearance
Wrap-up	~5 min	Git commit, discuss deployment options

npm install -g @anthropic-ai/claude-code

brew install claude-code

After installing, run claude in your terminal to start. You’ll be prompted to authenticate with your Anthropic account.

Recommended: Use a Claude subscription. Claude Pro ($20/mo) or Max ($100/mo or $200/mo) subscriptions include Claude Code usage — no surprise bills. This is the easiest option for the workshop.

If using the API instead: You can sign up for an Anthropic API account at console.anthropic.com. Before the workshop, set a spending limit — go to Settings → Limits and set a hard limit (e.g., $20). A typical 90-minute workshop session involves 15-30 substantial Claude interactions and costs roughly $5-15 on the API.

Rate limits: Pro subscription users may hit rate limits if making very rapid requests — if you see “too many requests” errors, wait 30-60 seconds and try again. Max plan ($100/mo or $200/mo) has more generous limits. Not sure which billing you’re on? Check claude.ai/settings for your plan, or console.anthropic.com for API billing.

Key Resources

Official docs: docs.anthropic.com/en/docs/claude-code/overview
GitHub repo: github.com/anthropics/claude-code
VS Code extension: Search “Claude Code” in the VS Code marketplace
Best practices: docs.anthropic.com/en/docs/claude-code/best-practices

Terminal Setup: The Multi-Window Workflow

The most important workflow pattern: run multiple terminal windows simultaneously.

The Three-Window Setup

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

Plus keep your browser open to http://localhost:4321 — it auto-refreshes as Claude makes changes.

Setting Up Split Panes

Cmd+D — Split pane vertically
Cmd+Shift+D — Split pane horizontally
Cmd+[ / Cmd+] — Switch between panes

Recommended: Claude Code in a tall left pane, dev server top-right, general terminal bottom-right.

Why This Matters

Watch your site rebuild in real-time as Claude makes changes
Alt-tab to the browser to see what Claude built, then go back to give feedback
Run git commits without interrupting Claude’s flow

Choosing a Framework

Comparison

Framework	Best For	Scaffold Command
Astro + Starlight	Wikis, research docs (our pick)	`npm create astro@latest -- --template starlight`
Docusaurus	Docs, blogs (Meta)	`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 .`

Why We Use Astro + Starlight

Markdown/MDX native — Write in Markdown, add React components when needed
Great defaults — Search, sidebar, dark mode, mobile-responsive out of the box
Fast — Static output, minimal client-side JS
LLM-friendly — MDX is the format Claude works best with
Auto-sidebar — Can auto-generate sidebar from folder structure (less config to manage)

This workshop assumes Starlight, but the Claude Code workflow is the same for any framework.

Non-Code Alternatives

Not everyone needs a code-based approach. If you prefer a more familiar tool, these can also produce research knowledge bases with AI assistance:

Tool	AI Integration	Publishing	Best For
Obsidian + Quartz	AI plugins, local-first	Quartz generates a static site from your vault	Personal research wikis, interlinked notes
Notion	Built-in Notion AI	Notion Sites or share publicly	Team wikis, collaborative docs
Google NotebookLM	Built-in (source-grounded)	Export only	Synthesizing a set of source documents, Q&A over your research

When to use these instead: If you don’t want to manage code, don’t need custom components, or prefer a GUI editor. They’re faster to start but less customizable and harder to scale past ~50 pages.

When to use the code approach (this workshop): If you want full control over structure and presentation, need custom interactive components, or are building something with 50+ pages that will evolve over time.

Workshop Walkthrough

Pick your research topic

Choose a topic in prioritization research, EA cause areas, or related domains that you know something about. For the hands-on session, aim for 3-5 sections with 2-4 pages each (10-20 pages total).

Good scope examples:
- “Key uncertainties in AI governance” (Policy Approaches, Technical Standards, International Coordination, Key Debates)
- “Guide to 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” (one page, not a wiki)
What makes a topic well-suited?
The best topics for this format share a few traits:
- Natural decomposition — The topic breaks cleanly into sections and sub-pages. If you can sketch 3-5 groups of 2-4 related subtopics, you have a good fit.
- Existing literature to synthesize — Claude draws on published material. Topics with substantial writing (blog posts, papers, reports) produce much better output than cutting-edge unpublished research.
- Value from organization, not original analysis — This format excels at structuring and connecting existing knowledge. If the value comes from novel calculations or original arguments, Claude will be unreliable.
- You can verify the output — Pick a topic you know well enough to catch errors. Claude will hallucinate facts, invent citations, and present contested claims as consensus. Your domain knowledge is the quality filter.
Topics to avoid: Anything requiring precise quantitative calculations (use a spreadsheet), topics where most sources are behind paywalls (Claude can’t access them), and topics where you’d be generating novel research claims rather than synthesizing existing ones.
Scaffold the project

Pick either option — both work fine for the workshop.
- Vanilla Starlight
- QURI Starter
A plain Starlight project. Simple and clean:
Terminal window
npm create astro@latest -- --template starlight my-wiki
The wizard will ask a few questions — pick:
- Install dependencies? → Yes
- Initialize a new git repository? → Yes
- TypeScript? → Strictest
Then: cd my-wiki
Windows users: Avoid paths with spaces (e.g., C:\Users\John Smith\...). Create your project in a short path like C:\projects\my-wiki instead.
Our pre-configured starter includes Mermaid diagrams, math rendering (KaTeX), React components, Tailwind CSS, and a CLAUDE.md. Useful if you know you’ll want these features:
Terminal window
npx degit quantified-uncertainty/cairn/starters/research-wiki my-wiki cd my-wiki npm install
This also includes example pages showing each feature in action — you’ll delete these when you create your own content.
Checkpoint: You should have a my-wiki/ folder with src/content/docs/, astro.config.mjs, and package.json.
Start the dev server (in Window 2)
Terminal window
```
npm run dev
```
Open http://localhost:4321 in your browser. If you used our starter, you should see “My Research Wiki” with a splash page. If you used vanilla Starlight, you should see “Welcome to Starlight.”

If port 4321 is already in use, start on another port: npm run dev -- --port 4322 (then open that port in your browser instead).

Checkpoint: Browser shows a working docs site.
Start Claude Code (in Window 1)
Terminal window
```
claude
```
Handling Permissions
Claude Code asks permission before editing files, reading directories, and running commands. You have options:
- Approve individually — Click “Allow” each time (safest, but slow)
- Allow for the session — Choose “Allow always” when prompted for common operations like file edits
- Skip all permissions — Start with claude --dangerously-skip-permissions to auto-approve everything. Only use this for throwaway workshop projects — it allows Claude to run arbitrary shell commands.
For the workshop, we recommend “Allow always” for file edits, or --dangerously-skip-permissions if you want maximum speed.

Create your entire page structure in one prompt

This is the magic moment. Give Claude a detailed prompt and watch it create your whole wiki skeleton. Use Shift+Enter for multi-line input, then Enter to submit.

Here’s a fully worked-out example you can adapt — this is what a real prompt looks like:

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.

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.

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
- A "Key Takeaways" section at the end
- 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 Claude finishes (~2-5 minutes), your browser should show your wiki with all sections in the sidebar and stub pages with introductions.

Check the browser and start expanding

Look at your site. Pick a page that interests you and start filling 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 improve based on 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.

Iterate in layers — this is where quality comes from. Your first prompt produces a scaffold; the next 2-3 prompts are what make it actually good. Here’s what a real iteration sequence looks like on a single page:

Turn	You say	What improves
1	”Create a page about compute governance”	You get a generic overview with placeholder-ish content
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.”	Real substance — specific proposals, 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?”	Analytical depth — the kind of questions researchers actually care about
4	”Add cross-references to the licensing-regimes and international-coordination pages.”	Connected knowledge base, not isolated pages

Each turn takes 1-2 minutes. Four turns gets you from generic to genuinely useful. The most common workshop mistake is creating 15 shallow pages instead of making 5 pages good.

If you’re stuck: try these prompts

During the content phase, if you’re not sure what to do next:

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 new 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”

Customize the appearance (~2 minutes, very satisfying)

Ask Claude:

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 including colors, fonts, and custom CSS.

Save your progress (in Window 3)
Terminal window
```
git add -A && git commit -m "workshop: initial research wiki"
```
Commit often — after the scaffold step, after expanding content, and before customizing appearance. If something goes wrong, git diff shows what changed and git checkout -- <file> reverts a specific file.

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

Claude Code Tips

Essential Commands

Command	What It Does
`claude`	Start Claude Code in current directory
`claude "prompt here"`	Start with an initial prompt
`claude --continue`	Resume your last conversation (if terminal crashed or you closed it)
Shift+Enter	New line (for multi-line prompts)
Enter	Submit your prompt
`/clear`	Clear conversation context (start fresh)
`/compact`	Compress conversation to save context window
`/init`	Auto-generate a CLAUDE.md for your project
`Ctrl+C`	Cancel current Claude operation
`Ctrl+D`	Exit Claude Code

When to use /clear vs /compact:

Situation	Use	Why
Claude is confused or producing bad output	`/clear`	Nuclear reset — throws away all context and starts fresh
You get a “context too long” warning or Claude forgets earlier instructions	`/compact`	Compresses the conversation into a summary, freeing space while keeping context
Switching to a completely different task	Start a new `claude` session	Clean slate with fresh permissions

Working Effectively

Give feedback, not just instructions. After Claude makes changes, look at the result in your browser and tell it what to fix:

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

Reference specific files when you want changes:

“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 gets confused, use /clear to reset context, or /compact to free up space. For a long session you may hit context limits — /compact is your friend.

When Claude asks about something you don’t care about, just say “your call” or “whatever you think is best” to keep things moving.

Check what changed after Claude does a big edit:

In Window 3, run git diff to see exactly what changed, or just check the browser.

If Claude creates files in the wrong place (e.g., docs/ instead of src/content/docs/), reference exact paths in your prompt. Add the correct path to CLAUDE.md so it remembers.

If your terminal crashes or disconnects, run claude --continue to resume your last conversation. Your files are safe — they’re on disk regardless of Claude’s session state.

CLAUDE.md: Teaching Claude About Your Project

The CLAUDE.md file in your project root is read by Claude Code automatically at the start of every session. It’s like a briefing document that gives Claude persistent context about your project’s structure, commands, and conventions.

Quick Setup

If you used the QURI starter, a CLAUDE.md is already included — you’re set.

Otherwise, the fastest way — ask Claude to create one:

/init

This auto-generates a CLAUDE.md based on your project’s files. Or ask Claude directly:

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.

Starter Template (Manual)

# 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

Why It Matters

Without CLAUDE.md, Claude starts fresh every conversation — it has to re-discover your project structure each time. With one, it immediately knows your commands, conventions, and patterns. This becomes critical once you’re past the workshop and working across multiple sessions.

Effective Prompting for Research Content

What Works Well

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.”

Reference existing pages as templates:

“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 — first get 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 Out For

LLMs hallucinate facts and citations — Review factual claims carefully, especially numbers, dates, quotes, and paper citations. When accuracy matters, ask Claude to search the web first.
MDX has quirks — Characters like <, {, and $ need escaping. If the build breaks, just paste the error to Claude and it’ll fix it.
Quality over quantity — 10 well-researched pages beats 30 shallow ones. Spend time iterating on content, not just creating more pages.
“Key Arguments” sections may be strawmen — Claude tends to present steelmanned versions of mainstream views and weak versions of minority positions. Check that opposing arguments are represented as their proponents would state them.
Quantitative claims need verification — Claude confidently produces numbers that are plausible but wrong. Any specific dollar amount, percentage, or date should be checked.
“Further Reading” links are often fake — Claude invents plausible-sounding URLs. Never trust a URL Claude generates without verification. Ask it to web-search for real links instead.
Content is often US/Western-centric — Explicitly prompt for global perspectives if your topic warrants them: “Include perspectives and examples from outside the US/Europe.”
All pages sound the same — After initial generation, pages tend toward the same generic voice. Fix by giving Claude a specific style reference or varying the depth you request per page.

Reviewing Content Effectively

The best workshop strategy: scaffold broadly, then review narrowly. Generate your full page structure in the first 20 minutes, then spend the remaining time deeply improving 3-5 pages rather than trying to make all 15 good.

For pages you want to actually trust, use this review approach:

Spot-check citations — If Claude names a specific paper, organization, or statistic, verify it exists. Ask: “Search the web to verify whether [specific claim] is accurate.”
Ask Claude to self-audit — “Read this page and list any claims you’re less than 80% confident are factually correct.” Claude is surprisingly good at flagging its own uncertainty when asked directly.
Check for missing perspectives — “What important perspectives or counterarguments are missing from this page?” This often surfaces viewpoints Claude omitted to present a cleaner narrative.
Look for false precision — Vague claims dressed up as specific ones (exact percentages, confident timelines, precise cost figures) are a hallmark of LLM content. Soften or verify these.

Useful Patterns

Instead of manually listing every page in astro.config.mjs, use directory-based auto-generation (this is what our starter prompts use):

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

Pages are ordered alphabetically by filename. Prefix with numbers for custom order: 01-intro.mdx, 02-background.mdx. Or use frontmatter sidebar: { order: 1 } to control ordering.

Adding Images

Put images in the public/ directory and reference them in MDX:

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

Tables Over Paragraphs

For comparisons, positions, or structured data, tables are almost always better 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

Link pages together — this is what makes a wiki a wiki, not just a collection of essays:

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

Deployment (After the Workshop)

When you’re ready to put your site online (a common gotcha: make sure npm run build succeeds locally before deploying — deployment platforms will fail on the same errors your local build does):

Push to GitHub
Go to vercel.com, sign up with GitHub (free tier available)
Click “Add New Project” → select your repo
It auto-detects Astro — just click Deploy
Your site is live at your-project.vercel.app

Zero configuration needed. Auto-deploys on every push. Deploys in 30-60 seconds.

Push your repo to GitHub
Go to netlify.com, sign in with GitHub
“Add new site” → “Import an existing project” → Select your repo
Build command: npm run build, Publish directory: dist/
Click Deploy — you’ll get a URL like your-site.netlify.app

Push to GitHub
Go to pages.cloudflare.com
Connect repo, set build command npm run build, output dist/

After the Workshop

Your research site is just getting started. Here’s how to keep building:

Deploy it — Having a live URL motivates you to keep improving. Takes 5 minutes with Netlify or Vercel.
Run /init to create a CLAUDE.md if you haven’t — makes every future session more productive
Add 3-5 pages per session — Even 30 minutes a week with Claude Code adds up fast
Focus on depth over breadth — Improve existing pages before adding more
Learn Starlight — The docs cover theming, custom components, i18n, and more
Ask Claude to create custom components — If you repeat a pattern (info boxes, comparison cards, cost-effectiveness tables), ask Claude to make it a reusable MDX component

What Scaled Projects Look Like

For LongTermWiki (~640 pages), we eventually added:

A CLI with 15 validators (link checking, quality scoring, etc.)
YAML-driven data layer with cross-references between entities
Custom React components for interactive content
Automated content improvement pipelines

You don’t need any of this to start — but it shows where the approach can go. The source is open at github.com/quantified-uncertainty/longterm-wiki.

Quick Reference Links

Resource	URL
Workshop slides	Google Slides
QURI	quantifieduncertainty.org
Claude Code docs	docs.anthropic.com/en/docs/claude-code/overview
Claude Code GitHub	github.com/anthropics/claude-code
Claude Code best practices	docs.anthropic.com/en/docs/claude-code/best-practices
Starlight docs	starlight.astro.build
Starlight frontmatter ref	starlight.astro.build/reference/frontmatter
Starlight theming	starlight.astro.build/guides/css-and-tailwind
Docusaurus docs	docusaurus.io
VitePress docs	vitepress.dev
Astro docs	docs.astro.build
MDX docs	mdxjs.com
QURI Starter template	`npx degit quantified-uncertainty/cairn/starters/research-wiki my-wiki`
LongTermWiki source	github.com/quantified-uncertainty/longterm-wiki

Troubleshooting

Setup & Installation

Node.js version too old or missing

Run node --version — you need 18+. If it says v16 or lower, or “command not found”, install from nodejs.org (LTS version)
If you use nvm: nvm install 18 && nvm use 18

Permission errors installing Claude Code (EACCES)

macOS/Linux: sudo npm install -g @anthropic-ai/claude-code
Or use npx @anthropic-ai/claude-code to run without global install

Claude Code authentication fails

Try claude logout then claude again to re-authenticate
Check you’re not behind a corporate VPN or proxy that blocks Anthropic’s API
If the browser doesn’t open for auth, copy the URL from the terminal and open it manually

npm create astro or npx degit hangs

Usually a network issue (especially on congested workshop WiFi). Try: npm cache clean --force and retry
Alternative: clone the QURI starter directly with git clone

Port 4321 already in use

Another process (maybe a previous dev server) is using it. Either kill it (lsof -i :4321 then kill <PID> on macOS/Linux), or start on a different port: npm run dev -- --port 4322

Build & Content Errors

Build errors after creating pages

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

Frontmatter YAML errors (YAMLException: bad indentation)

Usually a colon in the title without quotes. Fix: title: "AI: Key Questions" — wrap in quotes if the title contains colons, brackets, or other special characters

MDX import errors (SyntaxError: expected expression)

MDX imports must go at the top of the file, right after the frontmatter --- block, with no blank lines between imports
Claude sometimes puts imports in the middle of the file — move them to the top

Claude generates .md files instead of .mdx

Add to your CLAUDE.md: “Always use .mdx extension for all content files”
Or mention it in your prompt: “Use .mdx extension for all files”

Claude puts React/JSX components in MDX without importing them

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

Blank page — content exists but nothing renders

Usually missing or malformed frontmatter. Every .mdx file needs at minimum --- / title: "Page Title" / ---

Mermaid diagrams or math (KaTeX) not rendering

Vanilla Starlight doesn’t include these. Either use the QURI starter (which has them), or ask Claude: “Add Mermaid diagram support to this Starlight project”

Sidebar doesn’t show new pages

If using autogenerate, make sure the directory name in astro.config.mjs matches the actual folder name in src/content/docs/
If a section is totally missing from the sidebar, Claude probably forgot to add it to the config — ask it to check

Sidebar ordering is wrong (pages appear alphabetically)

Prefix filenames with numbers: 01-intro.mdx, 02-background.mdx
Or add sidebar: { order: 1 } to each page’s frontmatter
Or specify order explicitly in the sidebar config in astro.config.mjs

Links between pages return 404

Starlight URLs follow directory structure: src/content/docs/section/page.mdx → /section/page/. Note the trailing slash.
Double-check folder and file names match exactly (case-sensitive)

Images not showing (broken image icon)

Images in public/images/foo.png should be referenced as /images/foo.png (no public/ prefix in the path)

Claude Code Session Issues

Claude seems confused or repetitive

/clear — Reset context entirely (start a fresh conversation)
/compact — Compress conversation (keeps context summary, frees space)
Make sure you’re running claude from the project root directory, not a subdirectory

Claude keeps making the same mistake

Add the correction to CLAUDE.md — Claude reads this at the start of every session
e.g., “IMPORTANT: Always escape $ signs in MDX files”

Context window fills up — Claude forgets earlier instructions or output quality degrades

Use /compact to compress the conversation while keeping context
For very long sessions (30+ interactions), consider starting a fresh session with claude — your files persist on disk regardless

Claude creates files in the wrong directory

Be explicit: “Create files in src/content/docs/” — not just “create pages”
Add the path convention to your CLAUDE.md so Claude remembers across conversations

Claude modified the wrong file

Run git diff in Window 3 to see what changed. Revert a specific file with git checkout -- <file>
This is why committing after each phase matters — easy to roll back

Terminal crashed or disconnected

Run claude --continue to resume your last conversation with full context
Your files are safe on disk — the session state is separate from your project files

Rate limiting — “too many requests” error

Wait 30-60 seconds and retry. Pro plan has per-minute limits; space out your prompts slightly
Max plan ($100/mo or $200/mo) has more generous rate limits

Dev Server

Dev server crashed

Just restart it: npm run dev in Window 2
Common cause: a syntax error in an MDX file that Claude can fix — paste the terminal error to Claude

Dev server starts but hot reload stops working

Restart with Ctrl+C then npm run dev. This sometimes happens after many rapid file changes
If a page seems stuck, hard-refresh your browser (Cmd+Shift+R / Ctrl+Shift+R)

Pages show up but look wrong

Starlight handles most styling automatically — custom CSS rarely needed
If content looks garbled, it’s usually an MDX syntax issue (unescaped characters, unclosed tags)
Ask Claude: “The page at [path] looks broken in the browser. Read it and fix the MDX syntax.”

Content Quality

All pages sound identical — generic “this is an important topic” tone

Give Claude a specific voice: “Write in the style of a GiveWell cost-effectiveness analysis” or “Match the analytical tone of an 80,000 Hours career review”
Vary the depth: “This is a major page — write 1500 words with detailed analysis” vs. “This is a brief overview — 300 words max”

Claude invents organizations, papers, or statistics that don’t exist

Ask Claude to web-search before writing factual sections: “Search the web for real organizations working on X, then write this section”
Use the self-audit prompt: “Read this page and list any claims you’re less than 80% confident are factually correct”

“Further Reading” links point to non-existent URLs

Never trust URLs Claude generates without verification. Ask: “Search the web to find real, working URLs for the further reading section”

Claude avoids taking positions — everything is “some say X, others say Y”

Prompt specifically: “State which position has stronger evidence and why, while noting key uncertainties”

Tables are generic — vague “Pros/Cons” with no substance

Give Claude the exact column headers you want: “Create a table with columns: Proposal, Lead Organization, Implementation Status, Estimated Cost, Key Criticism”

Deployment

Build succeeds locally but fails on Netlify/Vercel

Usually a Node.js version mismatch. Set the Node version in your deploy platform’s settings to match your local version (node --version)
Or add "engines": { "node": ">=18" } to your package.json

Deployed site shows 404 for all pages

Check the base setting in astro.config.mjs. For Vercel/Netlify, base should be '/' or omitted.

Deployed site loads but styles are missing

Make sure site in astro.config.mjs matches your actual deployed URL (e.g., site: 'https://my-wiki.netlify.app')