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

Lucas Jellema
4 min readNov 29, 2021

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.

Code Tour provides a guided tour of the highlights of your code base (or the absolute low points)

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)
  • 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…



Lucas Jellema

Lucas Jellema is CTO and IT architect at Conclusion, The Netherlands. He is Oracle ACE Director, one time JavaOne Rockstar and programmer