Iterating on a reference Gitpod.yml that serves as a verbose 'documentation as code' which is intended to explain possibilities and how to configure them without folks needing to open a browser. Leave feedback on https://gist.github.com/ghuntley/1914fd5d15aec638d6dbb8d32d00f1e5 if you got any.

gitpod.yml reference

## Learn more about this file at 'https://www.gitpod.io/docs/references/gitpod-yml'
##
## This '.gitpod.yml' file when placed at the root of a project instructs
## Gitpod how to prepare & build the project, start development environments
## and configure continuous prebuilds. Prebuilds when enabled builds a project
## like a CI server so you can start coding right away - no more waiting for
## dependencies to download and builds to finish when reviewing pull-requests
## or hacking on something new.
##
## With Gitpod you can develop software from any device (even iPads) via 
## desktop or browser based versions of VS Code or any JetBrains IDE and
## customise it to your individual needs - from themes to extensions, you
## have full control.
##
## The easiest way to try out Gitpod is install the browser extenion:
## 'https://www.gitpod.io/docs/browser-extension' or by prefixing
## 'https://gitpod.io#' to the source control URL of any project.
##
## For example: 'https://gitpod.io#https://github.com/gitpod-io/gitpod'


## The 'image' section defines which Docker image Gitpod should use. 
## By default, Gitpod uses a standard Docker Image called 'workspace-full'
## which can be found at 'https://github.com/gitpod-io/workspace-images'
##
## Workspaces started based on this default image come pre-installed with
## Docker, Go, Java, Node.js, C/C++, Python, Ruby, Rust, PHP as well as
## tools such as Homebrew, Tailscale, Nginx and several more.
##
## If this image does not include the tools needed for your project then
## a public Docker image or your own Docker file can be configured.
## 
## Learn more about images at 'https://www.gitpod.io/docs/config-docker'

#image: node:buster                        # use 'https://hub.docker.com/_/node'
#image:
#  file: .gitpod.Dockerfile


## The 'tasks' section defines how Gitpod prepares & builds this project
## and how it can start development servers. With Gitpod, there are three
## types of tasks:
##
## - before: Use this for tasks that need to run before init and before command. 
## - init: Use this to configure prebuilds of heavy-lifting tasks such as
##         downloading dependencies or compiling source code.
## - command: Use this to start your database or application when the workspace starts.
##
## Learn more about these tasks at 'https://www.gitpod.io/docs/config-start-tasks'

#tasks:
#  - before: |
#      # commands to execute...
#
#  - init: |
#      # sudo apt-get install python3     # can be used to install operating system  which
#                                         # dependencies but these are after the prebuild
#                                         # completes thus Gitpod recommends moving
#                                         # operating system dependency installation steps
#                                         # to a custom Dockerfile to make prebuilds faster
#                                         # and to keep your codebase DRY.  
#                                         # 'https://www.gitpod.io/docs/config-docker'
#
#      # pip install -r requirements.txt  # install codebase dependencies
#      # cmake                            # precompile codebase
#
#  - name: Web Server
#    openMode: split-left
#    env:
#      WEBSERVER_PORT: 8080
#    command: |
#     python3 -m http.server $WEBSERVER_PORT
#
#  - name: Web Browser
#    openMode: split-right
#    env:
#      WEBSERVER_PORT: 8080
#    command: |
#     gp await-port $WEBSERVER_PORT
#     lynx `gp url`


## The 'ports' section defines various ports your may listen on are 
## configured in Gitpod on an authenticated URL. By default, all ports
## are in private visibility state.
##
## Learn more about ports at 'https://www.gitpod.io/docs/config-ports'

#ports:
#  - port: 8080 # alternatively configure entire ranges via '8080-8090'
#    visibility: private # either 'public' or 'private' (default)
#    onOpen: open-browser # either 'open-browser', 'open-preview' or 'ignore'


## The 'vscode' section defines a list of Visual Studio Code extensions from
## the OpenVSX.org registry to be installed upon workspace startup. OpenVSX
## is an open alternative to the proprietary Visual Studio Code Marketplace
## and extensions can be added by sending a pull-request with the extension
## identifier to https://github.com/open-vsx/publish-extensions
##
## The identifier of an extension is always ${publisher}.${name}.
##
## For example: 'vscodevim.vim'
##
## Learn more at 'https://www.gitpod.io/docs/ides-and-editors/vscode'

#vscode:
#  extensions: 
#    - vscodevim.vim
#    - esbenp.prettier-vscode@9.5.0
#    - https://example.com/abc/releases/extension-0.26.0.vsix


## The 'github' section defines configuration of continuous prebuilds
## for GitHub repositories when the GitHub application
## 'https://github.com/apps/gitpod-io' is installed in GitHub and granted
## permissions to access the repository.
##
## Learn more at 'https://www.gitpod.io/docs/prebuilds'

github: 
  prebuilds:
    # enable for the default branch
    master: true
    # enable for all branches in this repo
    branches: true
    # enable for pull requests coming from this repo
    pullRequests: true
    # enable for pull requests coming from forks
    pullRequestsFromForks: true
    # add a check to pull requests
    addCheck: true
    # add a "Review in Gitpod" button as a comment to pull requests
    addComment: false
    # add a "Review in Gitpod" button to the pull request's description
    addBadge: true

I like this! It reminds me of stable old things like the reference sendmail conf. 💌

One thing I'd find useful: several links to the docs, wherever applicable.
Can be tricky to maintain if the docs evolve over time 🤔 but it would be very useful I reckon.