This is a post that explain what the different parts of a Binder launch link mean.
What is a Binder launch link? This is one:
https://mybinder.org/v2/gh/binder-examples/requirements/master
If you click this link it will take you to a live binder based on the latest commit in the binder requirements.txt example repository. Why?
Basic patterns
A Binder link consists of three parts, in the case of the example above they are:
gh-
binder-examples/requirements, and master
The first part determines tells us that this repository is hosted on GitHub. Other options for this part are gl (Gitlab.com), gist (a GitHub gist) or git (any kind of git repository). The format for the the second part of the URL changes depending on which option you choose.
The second part of the URL (binder-examples/requirements) tells us which repository on GitHub.com we should pick. In this case it is the requirements repository in the binder-examples organisation. If instead you wanted to launch the conda repository from the same organisation this part would be binder-examples/conda.
The third part tells us which revision inside the repository we want to use. In this case we specify master. This isn’t actually a specific revision, so BinderHub will use the GitHub API to look up what revision that name corresponds to. You can use tags, branch names or actual revisions for this part. What things you can put here depends on the first part of the URL. For example if you are referring to a plain git repository you can’t put a name like master because there is no API BinderHub can talk to in order to find out what actual revision that name corresponds to.
This covers the basic parts of a Binder launch link. Go and experiment with them for a bit to get the hang out it. They look intimidating at first but there is method to the madness. I promise.
Advanced patterns
There are a two more advanced things you can do with Binder launch links once you are happy with how the basics work.
Directly opening a particular file
Sometimes you want to take people directly to a particular notebook or other file when they click you Binder launch link. For example https://mybinder.org/v2/gh/binder-examples/requirements/master?filepath=index.ipynb will take you straight to the index.ipynb notebook in the example repository. By specifying the filepath parameter you can send people to a view of (almost any) file in your repository. Make sure the path you specify is relative to the root of your repository.
Using a different user interface
Sometimes you want to send people straight to RStudio or Jupyter Lab instead of the classic notebook interface. Let’s use the R example repository to illustrate this.
The basic https://mybinder.org/v2/gh/binder-examples/r/master launch link will take you to the classic notebook UI. Compare that to https://mybinder.org/v2/gh/binder-examples/r/master?urlpath=rstudio which will take you to the RStudio interface.
If you open each of the two links in a new tab and wait for your Binders to launch you will see that the URL in your browsers will be different. For the basic launch link you will be on a page similar to https://hub.mybinder.org/user/binder-examples-r-b2xb8mb5/tree and for the RStudio one you will be at https://hub.mybinder.org/user/binder-examples-r-5r9dl00p/rstudio/. By specifying the urlpath parameter you replace the last part of the default URL (tree) with the value you specify.
For more examples on configuring user interfaces check https://mybinder.readthedocs.io/en/latest/howto/user_interface.html#user-interface
You have a lot of control on what users see depending on how you construct your Binder launch link. You can explore the possibilities via the form on http://mybinder.org/: watch how the generated link changes depending on which options you select from the drop down menus and which form fields you fill in.
(this post is a wiki post, this means you can directly edit it if you find typos or think a sentence could be clearer. Happy editing!)