Setting the file. One moment.
Subchapter 76.2
references/examples.mdMarkdown9 KBView on GitHub
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.
Tour file: https://github.com/microsoft/codetour/blob/main/.tours/intro.tour (opens in a new tab) Persona: New contributor Steps: ~5 · Depth: Standard
What makes it good:
### 🎥 Tour Player)[Gutter decorator](./src/player/decorator.ts)description field as a subtitle for the tour itselfTechnique 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\n\nSee also: [Gutter decorator](./src/player/decorator.ts)"
}Tour file: https://github.com/a11yproject/a11yproject.com/blob/main/.tours/code-tour.tour (opens in a new tab) Persona: External contributor Steps: 26 · Depth: Deep
What makes it good:
directory steps — orients to every src/ subdirectory without getting lost in filesselection on the opening step to highlight the exact entry in package.jsonTechnique 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."
}Tour file: https://github.com/github/codespaces-codeql/blob/main/.tours/codeql-tutorial.tour (opens in a new tab) Persona: Security engineer / concept learner Steps: 12 · Depth: Standard
What makes it good:
isPrimary: true — auto-launches when the Codespace openscommands array to run real VS Code commands mid-tour: the tour literally executes codeQL.runQuery when the reader arrives at that stepview 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 fileThis 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."
}Tour file: https://github.com/github/codespaces-learn-with-me/blob/main/.tours/main.tour (opens in a new tab) Persona: Total beginner Steps: 4 · Depth: Quick
What makes it good:
isPrimary: true for auto-launchTechnique to copy: For quick/vibecoder tours, cut mercilessly. Four steps that drive action beat twelve that explain everything.
Tour file: https://github.com/blackgirlbytes/copilot-todo-list/blob/main/.tours/main.tour (opens in a new tab) Persona: Concept learner / hands-on tutorial Steps: 28 · Depth: Deep
What makes it good:
file key) as progress milestones: “Check out your page! 🎉” and “Try it out!” between coding tasks>> npm install uuid; npm install styled-componentsTechnique 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."
}Tour files:
Persona: Platform engineer / architect Steps: 12 per tour · Depth: Standard
What makes it good:
nextTourselection coordinates used heavily in Terraform files where a block (not a single line) is the pointvscode.dev/github.com/... without cloningTechnique 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.
Tour files:
.tours/bazel.tour — Bazel workspace and build target orientation.tours/building-and-testing-the-python-bindings.tour — Python bindings BUILD.bazel walkthroughPersona: External contributor (build system focus) Steps: ~10 per tour
What makes it good:
main() — they start with whatever is confusing about this specific repo| Feature | When to use | Real example |
|---|---|---|
isPrimary: true | Auto-launch tour when repo opens (Codespace, vscode.dev) | codespaces-learn-with-me, codespaces-codeql |
commands: [...] | Run a VS Code command when reader arrives at this step | codespaces-codeql (codeQL.runQuery) |
view: "terminal" | Switch VS Code sidebar/panel at this step | codespaces-codeql (codeQLDatabases) |
pattern: "regex" | Match by line content, not number — use for volatile files | codespaces-codeql |
selection: {start, end} | Highlight a block (function body, config section, type def) | a11yproject, oci-2021, codespaces-codeql |
directory: "path/" | Orient to a folder without reading every file | a11yproject, codespaces-codeql |
uri: "https://..." | Link to PR, issue, RFC, ADR, external doc | Any PR review tour |
nextTour: "Title" | Chain tours in a series | oci-2021 (3-part series) |
| Checkpoint steps (content-only) | Progress milestones in long interactive tours | copilot-todo-list |
>> command in description | Terminal inline command link in VS Code | copilot-todo-list |
| Embedded image in description | Architecture diagrams, screenshots | microsoft/codetour |
Search all .tour files on GitHub:
https://github.com/search?q=path%3A**%2F*.tour+&type=code (opens in a new tab)
This search returns every .tour file committed to a public GitHub repo. Use it to:
commands, selection, pattern) is used in the wildFilter by language or keyword to narrow results — e.g. add language:TypeScript or fastapi to the query.