/code-tour

Real-World CodeTour Examples

Reference this file when you want to see how real repos use CodeTour features. Each example is sourced from a public GitHub repo with a direct link to the .tour file.

microsoft/codetour — Contributor orientation

Tour file: https://github.com/microsoft/codetour/blob/main/.tours/intro.tour Persona: New contributor Steps: ~5 · Depth: Standard

What makes it good:

• Intro step with an embedded SVG architecture diagram (raw GitHub URL inside the description)
• Rich markdown per step with emoji section headers (### 🎥 Tour Player)
• Inline cross-file links inside descriptions: [Gutter decorator](./src/player/decorator.ts)
• Uses the top-level description field as a subtitle for the tour itself

Technique to copy: Embed images and cross-links in descriptions to make them self-contained.

{
  "file": "src/player/index.ts",
  "line": 436,
  "description": "### 🎥 Tour Player\n\nThe CodeTour player ...\n\n![Architecture](https://raw.githubusercontent.com/.../overview.svg)\n\nSee also: [Gutter decorator](./src/player/decorator.ts)"
}

a11yproject/a11yproject.com — New contributor onboarding

Tour file: https://github.com/a11yproject/a11yproject.com/blob/main/.tours/code-tour.tour Persona: External contributor Steps: 26 · Depth: Deep

What makes it good:

• Almost entirely directory steps — orients to every src/ subdirectory without getting lost in files
• Conversational, beginner-friendly tone throughout
• selection on the opening step to highlight the exact entry in package.json
• Closes with a genuine thank-you and call-to-action

Technique to copy: Use directory steps as the skeleton of an onboarding tour — they teach structure without requiring the author to explain every file.

{
  "directory": "src/_data",
  "description": "This folder contains the **data files** for the site. Think of them as a lightweight database — YAML files that power the resource listings, posts index, and nav."
}

github/codespaces-codeql — The most technically complete example

Tour file: https://github.com/github/codespaces-codeql/blob/main/.tours/codeql-tutorial.tour Persona: Security engineer / concept learner Steps: 12 · Depth: Standard

What makes it good:

• isPrimary: true — auto-launches when the Codespace opens
• commands array to run real VS Code commands mid-tour: the tour literally executes codeQL.runQuery when the reader arrives at that step
• view property to switch the sidebar panel ("view": "codeQLDatabases")
• pattern instead of line for resilient matching: "pattern": "import tutorial.*"
• selection to highlight the exact select clause in a query file

This is the canonical reference for commands, view, and pattern.

{
  "file": "tutorial.ql",
  "pattern": "import tutorial.*",
  "view": "codeQLDatabases",
  "commands": ["codeQL.setDefaultTourDatabase", "codeQL.runQuery"],
  "title": "Run your first query",
  "description": "Click the **▶ Run** button above. The results appear in the CodeQL Query Results panel."
}

github/codespaces-learn-with-me — Minimal interactive tutorial

Tour file: https://github.com/github/codespaces-learn-with-me/blob/main/.tours/main.tour Persona: Total beginner Steps: 4 · Depth: Quick

What makes it good:

• Only 4 steps — proves that less is more for quick/vibecoder personas
• isPrimary: true for auto-launch
• Each step tells the reader to do something (edit a string, change a color) — not just read
• Ends with a tangible outcome: "your page is live"

Technique to copy: For quick/vibecoder tours, cut mercilessly. Four steps that drive action beat twelve that explain everything.

blackgirlbytes/copilot-todo-list — 28-step interactive tutorial

Tour file: https://github.com/blackgirlbytes/copilot-todo-list/blob/main/.tours/main.tour Persona: Concept learner / hands-on tutorial Steps: 28 · Depth: Deep

What makes it good:

• Uses content-only checkpoint steps (no file key) as progress milestones: "Check out your page! 🎉" and "Try it out!" between coding tasks
• Terminal inline commands in descriptions: >> npm install uuid; npm install styled-components
• Each file step shows the exact code the user should accept, in a markdown code fence, so they know the expected output

Technique to copy: Checkpoint steps (content-only, milestone title) break up long tours and give the reader a sense of progress.

{
  "title": "Check out your page! 🎉",
  "description": "Open the **Simple Browser** tab to see your to-do list. You should see all three tasks rendering from your data array.\n\nOnce you're happy with it, continue to add interactivity."
}

lucasjellema/cloudnative-on-oci-2021 — Multi-tour architecture series

Tour files:

• https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/function-tweet-retriever.tour
• https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/oci-and-infrastructure-as-code.tour
• https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/build-and-deployment-pipeline-function-tweet-retriever.tour

Persona: Platform engineer / architect Steps: 12 per tour · Depth: Standard

What makes it good:

• Three separate tours for three separate concerns (function code, IaC, CI/CD pipeline) — each standalone but linked via nextTour
• selection coordinates used heavily in Terraform files where a block (not a single line) is the point
• Steps include markdown links to official OCI documentation inline
• Designed to be browsed via vscode.dev/github.com/... without cloning

Technique to copy: For complex systems, write one tour per layer and chain them with nextTour. Don't try to cover infrastructure + application code + CI/CD in one tour.

SeleniumHQ/selenium — Monorepo build system onboarding

Tour files:

• .tours/bazel.tour — Bazel workspace and build target orientation
• .tours/building-and-testing-the-python-bindings.tour — Python bindings BUILD.bazel walkthrough

Persona: External contributor (build system focus) Steps: ~10 per tour

What makes it good:

• Targets a non-obvious entry point — not the product code but the build system
• Proves that "contributor onboarding" tours don't have to start with main() — they start with whatever is confusing about this specific repo
• Used in a large, mature OSS project at scale

Technique quick-reference

Discover more real tours on GitHub

Search all .tour files on GitHub: https://github.com/search?q=path%3A**%2F*.tour+&type=code

This search returns every .tour file committed to a public GitHub repo. Use it to:

• Find tours for repos in the same language/framework as the one you're working on
• Study how other authors handle the same personas or step types
• Look up how a specific field (commands, selection, pattern) is used in the wild

Filter by language or keyword to narrow results — e.g. add language:TypeScript or fastapi to the query.

Further reading

• DEV Community — "Onboard your codebase with CodeTour": https://dev.to/tobiastimm/onboard-your-codebase-with-codetour-2jc8
• Coder Blog — "Onboard to new projects faster with CodeTour": https://coder.com/blog/onboard-to-new-projects-faster-with-codetour
• Microsoft Tech Community — Educator Developer Blog: https://techcommunity.microsoft.com/blog/educatordeveloperblog/codetour-vscode-extension-allows-you-to-produce-interactive-guides-assessments-a/1274297
• AMIS Technology Blog — vscode.dev + CodeTour: https://technology.amis.nl/software-development/visual-studio-code-the-code-tours-extension-for-in-context-and-interactive-readme/
• CodeTour GitHub Topics: https://github.com/topics/codetour