Visual Studio Code–the Code Tours extension for in context and interactive readme image 45

Visual Studio Code–the Code Tours extension for in context and interactive readme

The most popular IDE – VS Code – comes with a ton of extensions, and each can make life easier, more productive and more fun for developers. Recently I came across the Code Tours extension. An extension that supports the creation of guided tours through the files in your VS Code workspace.image

A Code Tour consists of a series of descriptive steps – defined using markdown with rich formatting including code snippets, URL references, file links and images – and associated with specific locations in your sources.


A tour can guide a fellow developer through the sources much better and more pleasantly than any readme document could ever do. Using Code Tours, you can create very accessible:

  • explanations of involved flows through the code
  • analysis of bugs to be resolved
  • overviews of the changes created as part of a PR
  • descriptions of dependencies between multiple files
  • reading instructions across multiple sections in multiple documents
  • overviews of solution designs for new features and user stories
  • hands on instructions for a workshop or training

To get going with Code Tours:

  • Install the Code Tours extension in VS Code

  • Start recording a new Tour (for the current project)image
  • Add Code Tour Steps in the relevant locations in your sources


    The code tour is defined in a JSON document included in the project. You can edit that JSON document. It is included with the sources when the files are pushed to a Git repo. The Code Tour can also be exported and imported in a different VS Code instance – to allow sharing without having to push to a repo.
  • You can start your tour through a code base from the Code Tour pane and from any Code Tour Point of Interest in the code base


Here is an example of a code step that uses from of the layout options:


Using it is easy to share an example of a code base with some Code Tours. Navigate to this URL that is composed of and the URL for a GitHub repository. What this URL will do is launch (Visual Code in the browser) and load the code in that repository.


If you open the CodeTour pane, you will encounter several Code Tours. Run them to see the effected of being taken by the hand and shown around a code base.



VS Code Tours Extension

YouTube – VS Code tips — The CodeTour extension –

Tobias Timm – On board your code base with CodeTour –

My GitHub Repository with a Tour Guided Code Base:

Inspect that same code base in browser based VS Code :

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.