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