docs: rework titles (#1582)

docs/execute-notebooks.md

@@ -1,12 +1,13 @@
 ---
-title: Execute Notebooks During Your Build
-description: MyST can execute notebooks using Jupyter Server, making it possible to build rich websites and documents from text-based notebooks.
-short_title: Execute Notebooks During Your Build
+title: Execute Notebooks at Build Time
+subtitle: Generate figures and other rich content using Jupyter kernels
+short_title: Execute During Build
+description: MyST can execute Markdown files and Jupyter Notebooks, making it possible to build rich websites from computational documents.
 thumbnail: thumbnails/execute-notebooks.png
 ---
 
-:::{warning} MyST Execution is in Beta
-By default, execution is disabled and code outputs are only inserted if the notebook has already been executed (for text-based notebooks, there are no outputs).
+:::{warning} MyST execution features are in Beta
+By default, execution is disabled and computational outputs are only inserted if the notebook has already been executed (for text-based notebooks, there are no outputs!).
 We are adding support for executing markdown notebooks and ipynb files, including inline execution.
 As we are adding this functionality we appreciate any feedback from the community on how it is working in your environments. Please add [issues](https://github.com/jupyter-book/mystmd/issues/new) or join [Discord](https://discord.mystmd.org/) to give feedback.
 :::
@@ -49,9 +50,9 @@ print("Hello" + 10001)
 
 ## Skip particular code-cells
 
-Sometimes, you might have a notebook containing code that you _don't_ want to execute. For example, you might have code-cells that prompt the user for input, which should be skipped during a website build. MyST understands the same `skip-execution` cell-tag that other Jupyter Notebook tools (such as Jupyter Book) use to prevent a cell from being executed. 
+Sometimes, you might have a notebook containing code that you _don't_ want to execute. For example, you might have code-cells that prompt the user for input, which should be skipped during a website build. MyST understands the same `skip-execution` cell-tag that other Jupyter Notebook tools (such as Jupyter Book) use to prevent a cell from being executed.
 
-Using the {myst:directive}`code-cell` directive, the `skip-execution` tag can be added as follows:
+For [Markdown notebooks using the {myst:directive}`code-cell` directive](notebooks-with-markdown.md#code-cell), the `skip-execution` tag can be added as follows:
 
 ````markdown
 ```{code-cell}

docs/integrating-jupyter.md

@@ -1,13 +1,11 @@
 ---
-title: Integrate Jupyter-based Computation
-short_title: Live Computation with Jupyter
+title: In-Browser Execution
+subtitle: Connecting Jupyter Kernels to your MyST website
 description: MyST allows you to connect a website directly to a Jupyter Kernel, enabling interactive computation on your page.
 thumbnail: thumbnails/integrating-jupyter.png
 ---
 
-MyST allows you to connect a website directly to a Jupyter Kernel, enabling interactive computation on your page.
-
-This allows you to do some amazing things with your MyST website like:
+MyST allows you to connect a website directly to a Jupyter Kernel, allowing you to do some amazing things with your website like:
 
 - Allow readers to recompute your notebooks for themselves, demonstrating the reproducibility of your work
 - Provide a new level of interactive content via `ipywidgets` and `ipywidgets` backed libraries such as `ipympl`, `ipyleaflet`, etc...

docs/interactive-notebooks.ipynb

@@ -12,7 +12,9 @@
    },
    "source": [
     "---\n",
-    "title: Interactive Notebooks with MyST\n",
+    "title: Generate and Display Rich Outputs\n",
+    "short_title: Generate Rich Outputs\n",
+    "subtitle: Discover the types of cell outputs and metadata that MyST understands\n",
     "description: MyST allows you to include interactive visualizations directly in your projects using Jupyter Notebooks.\n",
     "thumbnail: ./thumbnails/interactive-notebooks.png\n",
     "---"

docs/myst.yml

@@ -103,11 +103,11 @@ project:
         - file: table-of-contents.md
     - title: Executable Content
       children:
-        - file: interactive-notebooks.ipynb
         - file: notebooks-with-markdown.md
+        - file: execute-notebooks.md
         - file: reuse-jupyter-outputs.md
+        - file: interactive-notebooks.ipynb
         - file: integrating-jupyter.md
-        - file: execute-notebooks.md
     - title: Websites
       children:
         - file: website-templates.md

docs/notebooks-with-markdown.md

@@ -1,33 +1,32 @@
 ---
+title: Executable Markdown Files
+subtitle: Define Jupyter metadata to make Markdown files executable
+description: MyST Markdown files can contain the necessary metadata required to execute their content.
 kernelspec:
   name: python3
   display_name: Python 3
 ---
 
-# Code Cells and Inline Expressions with Markdown
-
-```{warning} This is an alpha feature
-Markdown-based code cells are still in the works, and missing key functionality.
-Their behavior is subject to change unpredictably!
-```
 ```{code-cell} python
-:tag: hide-cell
+:tag: remove-cell
 
 import matplotlib.pyplot as plt
 import numpy as np
 ```
 
-You can specify Jupyter content in your Markdown, which allows you to execute computation using [MyST's notebook execution engine](./execute-notebooks.md). First, you will need to [define a kernel specification](#kernel-specification), after which you can introduce Markdown-based computation in several ways:
+Execution information can be added to MyST Markdown files, which allows you to perform computation using [MyST's notebook execution engine](./execute-notebooks.md). First, you will need to [define a kernel specification](#kernel-specification), after which you can introduce Markdown-based computation in several ways:
+
 - [Code cells](#code-cell) for block-level content.
 - [Inline expressions](#inline-expressions) for content inline with surrounding text.
 
-
 (kernel-specification)=
+
 ## Kernel specification
 
-Defining a kernel specification (`kernelspec`) informs the Jupyter server of the name of the kernel that should execute your code. When you call `myst build --execute` or `myst start --execute`, the MyST CLI starts a Jupyter kernel to execute your code and gather the execution results. Defining different `kernelspec`s in each notebook makes it possible to flexibly switch the package environment and programming language (e.g. to use R in one notebook, and Julia in another). 
+Defining a kernel specification (`kernelspec`) informs the Jupyter server of the name of the kernel that should execute your code. When you call `myst build --execute` or `myst start --execute`, the MyST CLI starts a Jupyter kernel to execute your code and gather the execution results. Defining different `kernelspec`s in each notebook makes it possible to flexibly switch the package environment and programming language (e.g. to use R in one notebook, and Julia in another).
+
+The `kernelspec` configuration should be defined in the _page-level_ frontmatter of each executable markdown file (see [](#field-behavior) for more information), and supports the same content that is validated by [`nbformat`'s schema](https://github.com/jupyter/nbformat/blob/main/nbformat/v4/nbformat.v4.5.schema.json):
 
-The `kernelspec` configuration should be defined in the *page-level* frontmatter of each executable markdown file (see [](#field-behavior) for more information), and supports the same content that is validated by [`nbformat`'s schema](https://github.com/jupyter/nbformat/blob/main/nbformat/v4/nbformat.v4.5.schema.json):
 ```{list-table} A list of available kernelspec fields
 :header-rows: 1
 :label: table-kernelspec
@@ -45,38 +44,37 @@ The following contents is a frontmatter defines a document that uses the `python
 ```yaml
 kernelspec:
   name: python3
-  display_name: "Python 3"
+  display_name: 'Python 3'
 ```
 
 After we declare the frontmatter, the contents of each {myst:directive}`code-cell` directive and {myst:role}`eval` role will be executed by the `python` kernel during the building process.
 
 ### Use a different kernel
+
 Furthermore, you can build MyST Markdown content with other programming languages like JavaScript, R, and Julia by installing the corresponding kernel. For example, to build a page that uses JavaScript in the {myst:directive}`code-cell`, we could:
+
 1. Install a JavaScript kernel, e.g. [ijavascript](https://github.com/n-riesco/ijavascript).
 2. Retrieve the kernel name with `jupyter kernelspec list`.  
    In the default installation, the kernel name is `javascript`.
 3. Set the kernelspec in your document's frontmatter:
-    ```yaml
-    kernelspec:
-      name: javascript
-      display_name: JavaScript
-    ```
+   ```yaml
+   kernelspec:
+     name: javascript
+     display_name: JavaScript
+   ```
 4. Define a code cell that uses the new kernel:
-    ````markdown
-    ```{code-cell} javascript
-    console.log("hello javascript kernel");
-    ```
-    ````
-
+   ````markdown
+   ```{code-cell} javascript
+   console.log("hello javascript kernel");
+   ```
+   ````
 
 (code-cell)=
 
 ## Code cells with the {myst:directive}`code-cell` directive
 
 You can use the {myst:directive}`code-cell` directive to create block-level computational outputs in MyST Markdown.
 
-
-
 {myst:directive}`code-cell` directives have the following form:
 
 ````
@@ -219,6 +217,7 @@ See [](./quickstart-jupyter-lab-myst.md) for how these eval statements also work
 In [](#compatibility-jupytext), the `jupytext` tool for integrating text-based notebooks with existing Jupyter tools like JupyterLab is discussed. By default, when reading a MyST Markdown document, `jupytext` creates a single Markdown cell between adjacent code cells. The block-break (`+++`) syntax described in [](./blocks.md) can be used to separate blocks of Markdown into distinct Markdown cells.
 
 (compatibility-jupytext)=
+
 ## Compatibility with `jupytext`
 
 [jupytext](https://github.com/mwouts/jupytext) is a Python package that converts between Jupyter Notebooks (ipynb files) and plain text documents (like MyST Markdown files). It provides both a commandline tool to perform these conversions, and an extension for JupyterLab to facilitate opening text-based notebooks with the Notebook viewer. MyST Markdown is understood by jupytext, which defines a `md:myst` format for reading from / writing to MyST Markdown.
@@ -228,5 +227,3 @@ The following command will convert a MyST markdown file `example.md` to the `.ip
 ```shell
 $ jupytext --from md:myst --to notebook example.md
 ```
-
-

docs/reuse-jupyter-outputs.md

@@ -1,7 +1,7 @@
 ---
 title: Embed and Reuse Jupyter Outputs
-subtitle: Embedding outputs in narrative articles
-short_title: Embed & Reuse Jupyter Outputs
+subtitle: Embedding generated outputs in narrative articles
+short_title: Embed & Reuse Outputs
 description: Embed Jupyter Notebook outputs from any notebook into your website or article.
 thumbnail: thumbnails/reuse-jupyter-outputs.png
 ---
@@ -15,6 +15,7 @@ A scientific article with two figures created in Jupyter Notebooks. Each figure
 ```
 
 (label-a-notebook-cell)=
+
 ## Label a Notebook Cell
 
 You can label notebook cells in two ways:
@@ -33,7 +34,7 @@ For example, the following comment in a Python cell sets a label[^black]:
 print("Hello world!")
 ```
 
-Note that `#` is the comment symbol for Python, but you'd use whatever symbol is used in the language for the notebook. 
+Note that `#` is the comment symbol for Python, but you'd use whatever symbol is used in the language for the notebook.
 
 **Add the label directly to the cell metadata**. Use a Jupyter interface or text editor to embed the label in the cell's metadata. For example, here's sample JSON that shows what metadata should look like:
 
@@ -120,6 +121,7 @@ For example, to embed **both the cell input and output**, use syntax like:
 ````
 
 % Embed both the input and output
+
 ```{embed} #tbl:data-cars
 :remove-output: false
 :remove-input: false
@@ -176,7 +178,6 @@ Adding alternative text to images allows you to provide context for the image fo
 By default, Jupyter does not support alternative text for image outputs, but you can use MyST to add alternative text with the {myst:directive}`figure` directive.
 See [](figures.md) for more details.
 
-
 Using the {myst:directive}`figure` directive allows you to set one or more captions for your figures, which serve accessibility purposes as well.
 This works for both static outputs (like Matplotlib) as well as interactive ones (like Altair).
 For example, the following {myst:directive}`figure` directive embeds two cell outputs with captions:
@@ -208,12 +209,12 @@ You can use a {myst:directive}`table` directive and **embed** the notebook outpu
 
 For example:
 
-````
+```
 :::{table} This is my table
 :label: mytable
 ![](#tbl:data-cars)
 :::
-````
+```
 
 Results in:
 
@@ -227,13 +228,13 @@ Results in:
 This defines a figure but allows the content to be a table.
 For example, the following syntax:
 
-````
+```
 :::{figure} #tbl:data-cars
 :label: myothertable
 :kind: table
 This is my table caption!
 :::
-````
+```
 
 Results in: