versions.json Structure

The internal structure of the versions.json file generated by the docs-versions-menu command is important for the Settings in conf.py of the docs-versions-menu.js_t template, and for index.html template.

The file contains a (nested) dictionary with the following keys:

  • 'downloads': a map from folder names to a list of tuples (text, url) for download items for that folder

  • 'folders': a list of all known folders

  • 'labels': a map from folder names to the label for each folder in the versions menu

  • 'latest': the latest stable release, or none

  • 'versions': the list of folders in the (reverse) order in which they should appear in the versions menu

  • 'warnings': a map from folder names to a list of warning labels for the warnings that should be displayed for that folder

  • 'default-branch': the name of the default branch, i.e. the first folder found according to the specificatin in the --default-branch option (usually main or master)

See Docs Version Menu’s own versions.json file for an example (formatted view).