Document the launch button functionality (#2046)

* Document the launch button functionality

* Update docs/website-launch-buttons.md

Co-authored-by: Angus Hollands <[email protected]>

* Update docs/website-launch-buttons.md

Co-authored-by: Angus Hollands <[email protected]>

* Update docs/website-launch-buttons.md

---------

Co-authored-by: Angus Hollands <[email protected]>

Author: choldgraf

docs/images/launch-button-menu.png

@@ -2,6 +2,7 @@ version: 1
 project:
   title: MyST Markdown
   github: https://github.com/jupyter-book/mystmd
+  # jupyter: true  # Uncomment to test launch buttons
   license:
     code: MIT
     content: CC-BY-4.0
@@ -109,6 +110,7 @@ project:
         - file: reuse-jupyter-outputs.md
         - file: interactive-notebooks.ipynb
         - file: integrating-jupyter.md
+        - file: website-launch-buttons.md
         - file: notebook-configuration.md
         - file: md-vs-ipynb.md
     - title: Websites

docs/myst.yml

@@ -1,13 +1,13 @@
 ---
-title: Notebook Configuration
+title: Add metadata to notebooks
 ---
 
 In Jupyter Notebooks you can add cell level configuration by specifying **tags** in the cell metadata.
 There are also global controls in the [project settings](#project-settings).
 
 (notebook-cell-tags)=
 
-### Notebook Cell Tags
+## Notebook Cell Tags
 
 Tags are a list of strings under the `tags` key in the cell metadata, which can be set in JupyterLab, VSCode or in a {myst:directive}`code-cell` directive.
 

docs/notebook-configuration.md

@@ -0,0 +1,32 @@
+---
+title: Launch Jupyter sessions
+---
+
+You can add a button to your MyST website that launches a Jupyter environment in the cloud and opens the current file in the editor. If the file is a Jupyter Notebook (`.ipynb` file) or a MyST document with code-cells[^lab-myst], users can use the Jupyter environment to run the code cells and inline expressions.[^thebe]
+
+[^thebe]: This is a fully-interactive Jupyter environment. If you'd instead like like to provide interactivity to the same page, see [](./integrating-jupyter.md).
+[^lab-myst]: Interacting with MyST Markdown documents is only supported in JupyterLab with [the `jupyterlab-myst` extension](https://jupyter-book.github.io/jupyterlab-myst/) installed.
+
+:::{caution} Launch buttons are experimental!
+We are still learning the best UX and configuration to control launch buttons, so they may change in the future!
+:::
+
+## Add a Jupyter server launch button
+
+To add a launch button to your project, ensure your project has GitHub configuration in your [project or page frontmatter](./frontmatter.md), then use the `project.jupyter: true` configuration. For example:
+
+```yaml
+project:
+  github: jupyter-book/mystmd
+  jupyter: true
+```
+
+This will add a "launch button" to the top of each page. Clicking the button will open a menu where you can paste in the URL of a JupyterHub or BinderHub to launch your content.
+Here's what it looks like:
+
+```{figure} ./images/launch-button-menu.png
+:width: 75%
+The launch button menu allows you to launch Jupyter servers on a JupyterHub or a Binder service. You can paste in the URL of the JupyterHub / BinderHub instance where you'd like to launch your content.
+```
+
+When you click {kbd}`Launch`, a Jupyter session will launch on the hub URL you've provided, and the source file of the current page will open.