diff --git a/docs/source/config_overview.md b/docs/source/config_overview.md
new file mode 100644
index 0000000000..946844f4ca
--- /dev/null
+++ b/docs/source/config_overview.md
@@ -0,0 +1,63 @@
+(configuration-overview)=
+
+# Configuration Overview
+
+Beyond the default configuration settings, you can configure a rich array of
+options to suit your workflow. Here are areas that are commonly configured
+when using Jupyter Notebook:
+
+> - {ref}`Jupyter's common configuration system <configure-common>`
+> - {ref}`Jupyter Server <configure-jupyter-server>`
+> - {ref}`Notebook extensions <configure-nbextensions>`
+
+Let's look at highlights of each area.
+
+(configure-common)=
+
+## Jupyter's Common Configuration system
+
+Jupyter applications, from the Notebook to JupyterHub to nbgrader, share a
+common configuration system. The process for creating a configuration file
+and editing settings is similar for all the Jupyter applications.
+
+> - [Jupyter’s Common Configuration Approach](https://jupyter.readthedocs.io/en/latest/use/config.html)
+> - [Common Directories and File Locations](https://jupyter.readthedocs.io/en/latest/use/jupyter-directories.html)
+> - [Language kernels](https://jupyter.readthedocs.io/en/latest/projects/kernels.html)
+> - [traitlets](https://traitlets.readthedocs.io/en/latest/config.html#module-traitlets.config)
+>   provide a low-level architecture for configuration.
+
+(configure-jupyter-server)=
+
+## Jupyter server
+
+The Jupyter Server runs the language kernel and communicates with the
+front-end Notebook client (i.e. the familiar notebook interface).
+
+> - Configuring the Jupyter Server
+>
+>   > To create a `jupyter_server_config.py` file in the `.jupyter`
+>   > directory, with all the defaults commented out, use the following
+>   > command:
+>   >
+>   > ```
+>   > $ jupyter server --generate-config
+>   > ```
+>
+> - [Running a Jupyter Server](https://jupyter-server.readthedocs.io/en/stable/operators/public-server.html)
+>
+> - Related: [Configuring a language kernel](https://ipython.readthedocs.io/en/latest/install/kernel_install.html)
+>   to run in the Jupyter Server enables your server to run other languages, like R or Julia.
+
+(configure-nbextensions)=
+
+## Notebook extensions
+
+The Notebook frontend can be extending with JupyterLab extensions.
+
+See the {ref}`Frontend Extension Guide <frontend-extensions>` for more information.
+
+[Security in Jupyter notebooks:](https://jupyter-server.readthedocs.io/en/stable/operators/security.html)
+Since security policies vary from organization to organization, we encourage you to
+consult with your security team on settings that would be best for your use
+cases. Our documentation offers some responsible security practices, and we
+recommend becoming familiar with the practices.
diff --git a/docs/source/config_overview.rst b/docs/source/config_overview.rst
deleted file mode 100644
index 7bafb9ba96..0000000000
--- a/docs/source/config_overview.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-.. _configuration-overview:
-
-Configuration Overview
-======================
-
-Beyond the default configuration settings, you can configure a rich array of
-options to suit your workflow. Here are areas that are commonly configured
-when using Jupyter Notebook:
-
-    - :ref:`Jupyter's common configuration system <configure_common>`
-    - :ref:`Jupyter Server <configure_jupyter_server>`
-    - :ref:`Notebook extensions <configure_nbextensions>`
-
-Let's look at highlights of each area.
-
-.. _configure_common:
-
-Jupyter's Common Configuration system
--------------------------------------
-Jupyter applications, from the Notebook to JupyterHub to nbgrader, share a
-common configuration system. The process for creating a configuration file
-and editing settings is similar for all the Jupyter applications.
-
-    - `Jupyter’s Common Configuration Approach <https://jupyter.readthedocs.io/en/latest/use/config.html>`_
-    - `Common Directories and File Locations <https://jupyter.readthedocs.io/en/latest/use/jupyter-directories.html>`_
-    - `Language kernels <https://jupyter.readthedocs.io/en/latest/projects/kernels.html>`_
-    - `traitlets <https://traitlets.readthedocs.io/en/latest/config.html#module-traitlets.config>`_
-      provide a low-level architecture for configuration.
-
-.. _configure_jupyter_server:
-
-Jupyter server
----------------
-
-The Jupyter Server runs the language kernel and communicates with the
-front-end Notebook client (i.e. the familiar notebook interface).
-
-  - Configuring the Jupyter Server
-
-      To create a ``jupyter_server_config.py`` file in the ``.jupyter``
-      directory, with all the defaults commented out, use the following
-      command::
-
-            $ jupyter server --generate-config
-
-  - `Running a Jupyter Server <https://jupyter-server.readthedocs.io/en/stable/operators/public-server.html>`_
-  - Related: `Configuring a language kernel <https://ipython.readthedocs.io/en/latest/install/kernel_install.html>`_
-    to run in the Jupyter Server enables your server to run other languages, like R or Julia.
-
-.. _configure_nbextensions:
-
-Notebook extensions
--------------------
-
-The Notebook frontend can be extending with JupyterLab extensions.
-
-See the :ref:`Frontend Extension Guide <frontend_extensions>` for more information.
-
-`Security in Jupyter notebooks:  <https://jupyter-server.readthedocs.io/en/stable/operators/security.html>`_
-Since security policies vary from organization to organization, we encourage you to
-consult with your security team on settings that would be best for your use
-cases. Our documentation offers some responsible security practices, and we
-recommend becoming familiar with the practices.
diff --git a/docs/source/configuration.md b/docs/source/configuration.md
new file mode 100644
index 0000000000..108bb1acd4
--- /dev/null
+++ b/docs/source/configuration.md
@@ -0,0 +1,10 @@
+# Configuration
+
+```{toctree}
+:caption: Configuration
+:maxdepth: 1
+
+config_overview
+Security <https://jupyter-server.readthedocs.io/en/stable/operators/security.html>
+extending/index.rst
+```
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
deleted file mode 100644
index 7e2d953600..0000000000
--- a/docs/source/configuration.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-=============
-Configuration
-=============
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Configuration
-
-   config_overview
-   Security <https://jupyter-server.readthedocs.io/en/stable/operators/security.html>
-   extending/index.rst
diff --git a/docs/source/contributor.md b/docs/source/contributor.md
new file mode 100644
index 0000000000..de041ef128
--- /dev/null
+++ b/docs/source/contributor.md
@@ -0,0 +1,9 @@
+# Contributor
+
+```{toctree}
+:caption: Contributor Documentation
+:maxdepth: 1
+
+contributing
+development_faq
+```
diff --git a/docs/source/contributor.rst b/docs/source/contributor.rst
deleted file mode 100644
index cba95d0246..0000000000
--- a/docs/source/contributor.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-===========
-Contributor
-===========
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contributor Documentation
-
-   contributing
-   development_faq
diff --git a/docs/source/development_faq.md b/docs/source/development_faq.md
new file mode 100644
index 0000000000..c6fd167116
--- /dev/null
+++ b/docs/source/development_faq.md
@@ -0,0 +1,9 @@
+(development-faq)=
+
+# Developer FAQ
+
+1. How do I install a prerelease version such as a beta or release candidate?
+
+```bash
+python -m pip install notebook --pre --upgrade
+```
diff --git a/docs/source/development_faq.rst b/docs/source/development_faq.rst
deleted file mode 100644
index 562d7fde8d..0000000000
--- a/docs/source/development_faq.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-.. _development_faq:
-
-Developer FAQ
-=============
-
-1. How do I install a prerelease version such as a beta or release candidate?
-
-.. code-block:: bash
-
-    python -m pip install notebook --pre --upgrade
diff --git a/docs/source/extending/frontend_extensions.rst b/docs/source/extending/frontend_extensions.md
similarity index 52%
rename from docs/source/extending/frontend_extensions.rst
rename to docs/source/extending/frontend_extensions.md
index aabfdaefc0..91944f4370 100644
--- a/docs/source/extending/frontend_extensions.rst
+++ b/docs/source/extending/frontend_extensions.md
@@ -1,8 +1,6 @@
-.. _frontend_extensions:
+(frontend-extensions)=
 
-===========================
-Custom front-end extensions
-===========================
+# Custom front-end extensions
 
 This describes the basic steps to write a TypeScript extension for the Jupyter
 notebook front-end. This allows you to customize the behaviour of the various
@@ -15,5 +13,5 @@ This means Notebook v7 is able to reuse many of the existing extensions from the
 
 If you would like to develop a prebuilt extension for Notebook v7, check out:
 
-- `JupyterLab Extension Tutorial <https://jupyterlab.readthedocs.io/en/latest/extension/extension_tutorial.html>`_: A tutorial to learn how to make a simple JupyterLab extension.
-- The `JupyterLab Extension Examples Repository <https://github.com/jupyterlab/extension-examples>`_: A short tutorial series to learn how to develop extensions for JupyterLab by example.
+- [JupyterLab Extension Tutorial](https://jupyterlab.readthedocs.io/en/latest/extension/extension_tutorial.html): A tutorial to learn how to make a simple JupyterLab extension.
+- The [JupyterLab Extension Examples Repository](https://github.com/jupyterlab/extension-examples): A short tutorial series to learn how to develop extensions for JupyterLab by example.
diff --git a/docs/source/extending/index.md b/docs/source/extending/index.md
new file mode 100644
index 0000000000..6635a827b8
--- /dev/null
+++ b/docs/source/extending/index.md
@@ -0,0 +1,12 @@
+# Extending the Notebook
+
+Certain subsystems of the notebook server are designed to be extended or
+overridden by users. These documents explain these systems, and show how to
+override the notebook's defaults with your own custom behavior.
+
+```{toctree}
+:maxdepth: 2
+
+Extending the Jupyter Server <https://jupyter-server.readthedocs.io/en/stable/developers/index.html>
+frontend_extensions
+```
diff --git a/docs/source/extending/index.rst b/docs/source/extending/index.rst
deleted file mode 100644
index c20309c5cf..0000000000
--- a/docs/source/extending/index.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-======================
-Extending the Notebook
-======================
-
-Certain subsystems of the notebook server are designed to be extended or
-overridden by users. These documents explain these systems, and show how to
-override the notebook's defaults with your own custom behavior.
-
-.. toctree::
-    :maxdepth: 2
-
-    Extending the Jupyter Server <https://jupyter-server.readthedocs.io/en/stable/developers/index.html>
-    frontend_extensions
diff --git a/docs/source/index.md b/docs/source/index.md
new file mode 100644
index 0000000000..aa156d75de
--- /dev/null
+++ b/docs/source/index.md
@@ -0,0 +1,17 @@
+# The Jupyter Notebook
+
+```{image} ./_static/images/notebook-running-code.png
+
+```
+
+- [Installation](https://jupyter.readthedocs.io/en/latest/install.html)
+- [Starting the Notebook](https://jupyter.readthedocs.io/en/latest/running.html)
+
+```{toctree}
+:maxdepth: 2
+
+user-documentation
+configuration
+contributor
+migrate_to_notebook7
+```
diff --git a/docs/source/index.rst b/docs/source/index.rst
deleted file mode 100644
index e87b46012e..0000000000
--- a/docs/source/index.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-====================
-The Jupyter Notebook
-====================
-
-
-.. image:: ./_static/images/notebook-running-code.png
-
-* `Installation <https://jupyter.readthedocs.io/en/latest/install.html>`_
-* `Starting the Notebook <https://jupyter.readthedocs.io/en/latest/running.html>`_
-
-.. toctree::
-   :maxdepth: 2
-
-   user-documentation
-   configuration
-   contributor
-   migrate_to_notebook7
diff --git a/docs/source/migrate_to_notebook7.rst b/docs/source/migrate_to_notebook7.md
similarity index 53%
rename from docs/source/migrate_to_notebook7.rst
rename to docs/source/migrate_to_notebook7.md
index dd03929266..28d719703d 100644
--- a/docs/source/migrate_to_notebook7.rst
+++ b/docs/source/migrate_to_notebook7.md
@@ -1,38 +1,34 @@
-Migrating to Notebook 7
-=======================
+# Migrating to Notebook 7
 
-Build Jupyter Notebook v7 off of JupyterLab components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Build Jupyter Notebook v7 off of JupyterLab components
 
 Read more details about the changes currently taking place in the
-Jupyter Ecosystem in the `JEP 79`_ and `team-compass note`_.
+Jupyter Ecosystem in the [JEP 79] and [team-compass note].
 
 Notebook 7 is built on top of JupyterLab components and delivers new features
 like realtime collaboration, debugger, theming.
 
-Compatibility with older versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Compatibility with older versions
 
-Any extension developed for Notebook < 7 or NbClassic will not be
+Any extension developed for Notebook \< 7 or NbClassic will not be
 compatible with Notebook 7 and upwards.
 
 Some extensions like nbgrader have already been ported. We invite you to
 check if the extensions you are using have already been ported.
 
-Simulaneous usage of different versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Simulaneous usage of different versions
 
 **NbClassic and Notebook 7**
 
 You can install NbClassic, Notebook 7 and JupyterLab, all three of
 which will provide different user interfaces
 on the same server. When Notebook 7 is available, the NbClassic UI, will
-be served at the ``/nbclassic/tree`` base path rather than the
-base path ``/tree`` used otherwise. If you are using Notebook 7 along
+be served at the `/nbclassic/tree` base path rather than the
+base path `/tree` used otherwise. If you are using Notebook 7 along
 with NbClassic, you will also have JupyterLab installed as it is a
 dependency of Notebook 7, and these front ends will be available
-through the following base paths: JupyterLab at ``/lab``, Notebook 7 at
-``/tree``, and NbClassic at ``/nbclassic/tree``.
+through the following base paths: JupyterLab at `/lab`, Notebook 7 at
+`/tree`, and NbClassic at `/nbclassic/tree`.
 
 **NbClassic and Notebook 6.5.x**
 
@@ -40,46 +36,46 @@ As NbClassic provides the static assets for Notebook 6.5.x, while
 having both installed should cause no issues, the user interface provided
 by these two packages will be the same. These UIs will be served by
 different back end servers. An NbClassic instance will be at a server with the
-``/tree`` path and opening a Notebook 6.5.x instance will open on a
-different server with the ``/tree`` path as well, presenting the same
+`/tree` path and opening a Notebook 6.5.x instance will open on a
+different server with the `/tree` path as well, presenting the same
 static assets. When starting an instance of JupyterLab you will be able
 to access the classic view of Notebook with NbClassic served on the same
-server at ``/tree``.
+server at `/tree`.
 
-**NbClassic and Notebook <= 6.4.x**
+**NbClassic and Notebook \<= 6.4.x**
 
-When using NbClassic and Notebook <= 6.4.x you can expect that these UIs
+When using NbClassic and Notebook \<= 6.4.x you can expect that these UIs
 will not be only presented at different servers, meaning they will both
-be available at their respective server under ``/tree`` but they
+be available at their respective server under `/tree` but they
 may also differ as potential changes to the NbClassic UI will not be
-reflected in Notebook versions <= 6.4.x. In this case as well, you would
+reflected in Notebook versions \<= 6.4.x. In this case as well, you would
 be able to access the classic view of Notebook with NbClassic served on
-the same server, at ``/tree``.
+the same server, at `/tree`.
 
 **NbClassic and JupyterLab 3.x**
 
 When only JupyterLab 3.x is installed, then NbClassic does not have to be
 explicitly installed as JupyterLab 3.x depends on it. They will run on
-the same server, and are reachable via ``/tree`` for NbClassic and
-``/lab`` for JupyterLab.
+the same server, and are reachable via `/tree` for NbClassic and
+`/lab` for JupyterLab.
 
 **NbClassic and JupyterLab 4.x**
 
 When only JupyterLab 4.x is installed, then NbClassic has to be installed
 explictly. They will run on the same server, and are reachable via
-``/tree`` for NbClassic, and ``/lab`` for JupyterLab.
+`/tree` for NbClassic, and `/lab` for JupyterLab.
 
 **NbClassic Independently**
 
-When you choose to install only NbClassic via ``pip install nbclassic``,
-the classic Notebook UI will be presented at the ``/tree`` path. As the
+When you choose to install only NbClassic via `pip install nbclassic`,
+the classic Notebook UI will be presented at the `/tree` path. As the
 other frontends are not installed, attempting to access the other paths
 will return errors. Note that NbClassic being a Jupyter Server extension,
 indicated Jupyter Server will be available. This provides an additional
-way to view the NbClassic frontend. You would be able to  manually
+way to view the NbClassic frontend. You would be able to manually
 enable the extension when running an instance of Jupyter Server,
-``> jupyter server --ServerApp.jpserver_extensions="nbclassic=True"``,
-which will provide the NbClassic frontend at ``/tree`` path when visited.
+`> jupyter server --ServerApp.jpserver_extensions="nbclassic=True"`,
+which will provide the NbClassic frontend at `/tree` path when visited.
 
-.. _JEP 79: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
-.. _team-compass note: https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000
+[jep 79]: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
+[team-compass note]: https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000
diff --git a/docs/source/notebook.rst b/docs/source/notebook.md
similarity index 53%
rename from docs/source/notebook.rst
rename to docs/source/notebook.md
index 903ef88a18..047be966b9 100644
--- a/docs/source/notebook.rst
+++ b/docs/source/notebook.md
@@ -1,15 +1,13 @@
-.. _htmlnotebook:
+(htmlnotebook)=
 
-The Jupyter Notebook
-====================
+# The Jupyter Notebook
 
-Introduction
-------------
+## Introduction
 
 The notebook extends the console-based approach to interactive computing in
 a qualitatively new direction, providing a web-based application suitable for
 capturing the whole computation process: developing, documenting, and
-executing code, as well as communicating the results.  The Jupyter notebook
+executing code, as well as communicating the results. The Jupyter notebook
 combines two components:
 
 **A web application**: a browser-based tool for interactive authoring of
@@ -20,79 +18,62 @@ rich media output.
 application, including inputs and outputs of the computations, explanatory
 text, mathematics, images, and rich media representations of objects.
 
-.. seealso::
+:::{seealso}
+See the {ref}`installation guide <jupyter:install>` on how to install the
+notebook and its dependencies.
+:::
 
-    See the :ref:`installation guide <jupyter:install>` on how to install the
-    notebook and its dependencies.
+### Main features of the web application
 
-
-Main features of the web application
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-* In-browser editing for code, with automatic syntax highlighting,
+- In-browser editing for code, with automatic syntax highlighting,
   indentation, and tab completion/introspection.
-
-* The ability to execute code from the browser, with the results of
+- The ability to execute code from the browser, with the results of
   computations attached to the code which generated them.
-
-* Displaying the result of computation using rich media representations, such
+- Displaying the result of computation using rich media representations, such
   as HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figures
-  rendered by the matplotlib_ library, can be included inline.
-
-* In-browser editing for rich text using the Markdown_ markup language, which
+  rendered by the [matplotlib] library, can be included inline.
+- In-browser editing for rich text using the [Markdown] markup language, which
   can provide commentary for the code, is not limited to plain text.
+- The ability to easily include mathematical notation within markdown cells
+  using LaTeX, and rendered natively by [MathJax].
 
-* The ability to easily include mathematical notation within markdown cells
-  using LaTeX, and rendered natively by MathJax_.
-
-
-
-.. _MathJax: https://www.mathjax.org/
+### Notebook documents
 
-
-Notebook documents
-~~~~~~~~~~~~~~~~~~
 Notebook documents contains the inputs and outputs of a interactive session as
 well as additional text that accompanies the code but is not meant for
-execution.  In this way, notebook files can serve as a complete computational
+execution. In this way, notebook files can serve as a complete computational
 record of a session, interleaving executable code with explanatory text,
 mathematics, and rich representations of resulting objects. These documents
-are internally JSON_ files and are saved with the ``.ipynb`` extension. Since
+are internally [JSON] files and are saved with the `.ipynb` extension. Since
 JSON is a plain text format, they can be version-controlled and shared with
 colleagues.
 
-.. _JSON: https://en.wikipedia.org/wiki/JSON
-
 Notebooks may be exported to a range of static formats, including HTML (for
 example, for blog posts), reStructuredText, LaTeX, PDF, and slide shows, via
-the nbconvert_ command.
+the [nbconvert] command.
 
-Furthermore, any  ``.ipynb`` notebook document available from a public
-URL can be shared via the Jupyter Notebook Viewer <nbviewer>.
+Furthermore, any `.ipynb` notebook document available from a public
+URL can be shared via the Jupyter Notebook Viewer \<nbviewer>.
 This service loads the notebook document from the URL and renders it as a
-static web page.  The results may thus be shared with a colleague, or as a
+static web page. The results may thus be shared with a colleague, or as a
 public blog post, without other users needing to install the Jupyter notebook
-themselves.  In effect, nbviewer is simply nbconvert_ as
+themselves. In effect, nbviewer is simply [nbconvert] as
 a web service, so you can do your own static conversions with nbconvert,
 without relying on nbviewer.
 
+:::{seealso}
+{ref}`Details on the notebook JSON file format <nbformat:notebook_file_format>`
+:::
 
-
-.. seealso::
-
-    :ref:`Details on the notebook JSON file format <nbformat:notebook_file_format>`
-
-
-Notebooks and privacy
-~~~~~~~~~~~~~~~~~~~~~
+### Notebooks and privacy
 
 Because you use Jupyter in a web browser, some people are understandably
 concerned about using it with sensitive data.
 However, if you followed the standard
-`install instructions <https://jupyter.readthedocs.io/en/latest/install.html>`_,
+[install instructions](https://jupyter.readthedocs.io/en/latest/install.html),
 Jupyter is actually running on your own computer.
-If the URL in the address bar starts with ``http://localhost:`` or
-``http://127.0.0.1:``, it's your computer acting as the server.
+If the URL in the address bar starts with `http://localhost:` or
+`http://127.0.0.1:`, it's your computer acting as the server.
 Jupyter doesn't send your data anywhere else—and as it's open source,
 other people can check that we're being honest about this.
 
@@ -102,114 +83,116 @@ If you want to work with sensitive data in those cases,
 talk to your IT or data protection staff about it.
 
 We aim to ensure that other pages in your browser or other users on the same
-computer can't access your notebook server. See the `security documentation <https://jupyter-server.readthedocs.io/en/stable/operators/security.html>`__  for
+computer can't access your notebook server. See the [security documentation](https://jupyter-server.readthedocs.io/en/stable/operators/security.html) for
 more about this.
 
-
-Starting the notebook server
-----------------------------
+## Starting the notebook server
 
 You can start running a notebook server from the command line using the
-following command::
+following command:
 
-    jupyter notebook
+```
+jupyter notebook
+```
 
 This will print some information about the notebook server in your console,
 and open a web browser to the URL of the web application (by default,
-``http://127.0.0.1:8888``).
+`http://127.0.0.1:8888`).
 
 The landing page of the Jupyter notebook web application, the **dashboard**,
 shows the notebooks currently available in the notebook directory (by default,
 the directory from which the notebook server was started).
 
-You can create new notebooks from the dashboard with the ``New Notebook``
-button, or open existing ones by clicking on their name.  You can also drag
-and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
+You can create new notebooks from the dashboard with the `New Notebook`
+button, or open existing ones by clicking on their name. You can also drag
+and drop `.ipynb` notebooks and standard `.py` Python source code files
 into the notebook list area.
 
 When starting a notebook server from the command line, you can also open a
-particular notebook directly, bypassing the dashboard, with ``jupyter notebook
-my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
+particular notebook directly, bypassing the dashboard, with `jupyter notebook my_notebook.ipynb`. The `.ipynb` extension is assumed if no extension is
 given.
 
 When you are inside an open notebook, the `File | Open...` menu option will
 open the dashboard in a new browser tab, to allow you to open another notebook
 from the notebook directory or to create a new notebook.
 
+:::{note}
+You can start more than one notebook server at the same time, if you want
+to work on notebooks in different directories. By default the first
+notebook server starts on port 8888, and later notebook servers search for
+ports near that one. You can also manually specify the port with the
+`--port` option.
+:::
 
-.. note::
-
-   You can start more than one notebook server at the same time, if you want
-   to work on notebooks in different directories.  By default the first
-   notebook server starts on port 8888, and later notebook servers search for
-   ports near that one.  You can also manually specify the port with the
-   ``--port`` option.
-
-Creating a new notebook document
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Creating a new notebook document
 
 A new notebook may be created at any time, either from the dashboard, or using
-the :menuselection:`File --> New` menu option from within an active notebook.
+the {menuselection}`File --> New` menu option from within an active notebook.
 The new notebook is created within the same directory and will open in a new
 browser tab. It will also be reflected as a new entry in the notebook list on
 the dashboard.
 
-.. image:: _static/images/new-notebook.gif
+```{image} _static/images/new-notebook.gif
 
+```
+
+### Opening notebooks
 
-Opening notebooks
-~~~~~~~~~~~~~~~~~
 An open notebook has **exactly one** interactive session connected to a
 kernel, which will execute code sent by the user
-and communicate back results.  This kernel remains active if the web browser
+and communicate back results. This kernel remains active if the web browser
 window is closed, and reopening the same notebook from the dashboard will
 reconnect the web application to the same kernel. In the dashboard, notebooks
-with an active kernel have a ``Shutdown`` button next to them, whereas
-notebooks without an active kernel have a ``Delete`` button in its place.
+with an active kernel have a `Shutdown` button next to them, whereas
+notebooks without an active kernel have a `Delete` button in its place.
 
 Other clients may connect to the same kernel.
 When each kernel is started, the notebook server prints to the terminal a
-message like this::
+message like this:
 
-    [JupyterNotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
+```
+[JupyterNotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
+```
 
 This long string is the kernel's ID which is sufficient for getting the
 information necessary to connect to the kernel. If the notebook uses the IPython
 kernel, you can also see this
-connection data by running the ``%connect_info`` :ref:`magic
-<magics_explained>`, which will print the same ID information along with other
+connection data by running the `%connect_info` {ref}`magic <magics_explained>`, which will print the same ID information along with other
 details.
 
-You can then, for example, manually start a Qt console connected to the *same*
-kernel from the command line, by passing a portion of the ID::
+You can then, for example, manually start a Qt console connected to the _same_
+kernel from the command line, by passing a portion of the ID:
 
-    $ jupyter qtconsole --existing 87f7d2c0
+```
+$ jupyter qtconsole --existing 87f7d2c0
+```
 
-Without an ID, ``--existing`` will  connect to the most recently
+Without an ID, `--existing` will connect to the most recently
 started kernel.
 
-With the IPython kernel, you can also run the ``%qtconsole``
-:ref:`magic <magics_explained>` in the notebook to open a Qt console connected
+With the IPython kernel, you can also run the `%qtconsole`
+{ref}`magic <magics_explained>` in the notebook to open a Qt console connected
 to the same kernel.
 
-.. seealso::
-
-    :ref:`ipythonzmq`
+:::{seealso}
+{ref}`ipythonzmq`
+:::
 
-Notebook user interface
------------------------
+## Notebook user interface
 
 When you create a new notebook document, you will be presented with the
 **notebook name**, a **menu bar**, a **toolbar** and an empty **code cell**.
 
-.. image:: ./_static/images/blank-notebook-ui.png
+```{image} ./_static/images/blank-notebook-ui.png
+
+```
 
 **Notebook name**: The name displayed at the top of the page,
-next to the Jupyter logo, reflects the name of the ``.ipynb`` file.
+next to the Jupyter logo, reflects the name of the `.ipynb` file.
 Clicking on the notebook name brings up a dialog which allows you to rename it.
 Thus, renaming a notebook
 from "Untitled0" to "My first notebook" in the browser, renames the
-``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
+`Untitled0.ipynb` file to `My first notebook.ipynb`.
 
 **Menu bar**: The menu bar presents different options that may be used to
 manipulate the way the notebook functions.
@@ -219,52 +202,49 @@ operations within the notebook, by clicking on an icon.
 
 **Code cell**: the default type of cell; read on for an explanation of cells.
 
+## Structure of a notebook document
 
-Structure of a notebook document
---------------------------------
-
-The notebook consists of a sequence of cells.  A cell is a multiline text input
-field, and its contents can be executed by using :kbd:`Shift-Enter`, or by
-clicking either the "Play" button the toolbar, or :guilabel:`Cell`, :guilabel:`Run` in the menu bar.
-The execution behavior of a cell is determined by the cell's type.  There are three
-types of cells: **code cells**, **markdown cells**, and **raw cells**.  Every
+The notebook consists of a sequence of cells. A cell is a multiline text input
+field, and its contents can be executed by using {kbd}`Shift-Enter`, or by
+clicking either the "Play" button the toolbar, or {guilabel}`Cell`, {guilabel}`Run` in the menu bar.
+The execution behavior of a cell is determined by the cell's type. There are three
+types of cells: **code cells**, **markdown cells**, and **raw cells**. Every
 cell starts off being a **code cell**, but its type can be changed by using a
 drop-down on the toolbar (which will be "Code", initially), or via
-:ref:`keyboard shortcuts <keyboard-shortcuts>`.
+{ref}`keyboard shortcuts <keyboard-shortcuts>`.
 
 For more information on the different things you can do in a notebook,
-see the `collection of examples
-<https://nbviewer.jupyter.org/github/jupyter/notebook/tree/main/docs/source/examples/Notebook/>`_.
+see the [collection of examples](https://nbviewer.jupyter.org/github/jupyter/notebook/tree/main/docs/source/examples/Notebook/).
 
-Code cells
-~~~~~~~~~~
-A *code cell* allows you to edit and write new code, with full syntax
+### Code cells
+
+A _code cell_ allows you to edit and write new code, with full syntax
 highlighting and tab completion. The programming language you use depends
-on the *kernel*, and the default kernel (IPython) runs Python code.
+on the _kernel_, and the default kernel (IPython) runs Python code.
 
 When a code cell is executed, code that it contains is sent to the kernel
-associated with the notebook.  The results that are returned from this
-computation  are then displayed in the notebook as the cell's *output*. The
+associated with the notebook. The results that are returned from this
+computation are then displayed in the notebook as the cell's _output_. The
 output is not limited to text, with many other possible forms of output are
-also possible, including ``matplotlib`` figures and HTML tables (as used, for
-example, in the ``pandas`` data analysis package). This is known as IPython's
-*rich display* capability.
+also possible, including `matplotlib` figures and HTML tables (as used, for
+example, in the `pandas` data analysis package). This is known as IPython's
+_rich display_ capability.
 
-.. seealso::
+:::{seealso}
+[Rich Output] example notebook
+:::
 
-   `Rich Output`_  example notebook
+### Markdown cells
 
-Markdown cells
-~~~~~~~~~~~~~~
 You can document the computational process in a literate way, alternating
-descriptive text with code, using *rich text*. In IPython this is accomplished
+descriptive text with code, using _rich text_. In IPython this is accomplished
 by marking up text with the Markdown language. The corresponding cells are
-called *Markdown cells*. The Markdown language provides a simple way to
+called _Markdown cells_. The Markdown language provides a simple way to
 perform this text markup, that is, to specify which parts of the text should
 be emphasized (italics), bold, form lists, etc.
 
 If you want to provide structure for your document, you can use markdown
-headings. Markdown headings consist of 1 to 6 hash # signs ``#`` followed by a
+headings. Markdown headings consist of 1 to 6 hash # signs `#` followed by a
 space and the title of your section. The markdown heading will be converted
 to a clickable link for a section of the notebook. It is also used as a hint
 when exporting to other document formats, like PDF.
@@ -273,44 +253,40 @@ When a Markdown cell is executed, the Markdown code is converted into
 the corresponding formatted rich text. Markdown allows arbitrary HTML code for
 formatting.
 
-Within Markdown cells, you can also include *mathematics* in a straightforward
-way, using standard LaTeX notation: ``$...$`` for inline mathematics and
-``$$...$$`` for displayed mathematics. When the Markdown cell is executed,
+Within Markdown cells, you can also include _mathematics_ in a straightforward
+way, using standard LaTeX notation: `$...$` for inline mathematics and
+`$$...$$` for displayed mathematics. When the Markdown cell is executed,
 the LaTeX portions are automatically rendered in the HTML output as equations
-with high quality typography. This is made possible by MathJax_, which
-supports a `large subset <https://docs.mathjax.org/en/latest/input/tex/index.html>`__ of LaTeX functionality
+with high quality typography. This is made possible by [MathJax], which
+supports a [large subset](https://docs.mathjax.org/en/latest/input/tex/index.html) of LaTeX functionality
 
 Standard mathematics environments defined by LaTeX and AMS-LaTeX (the
-``amsmath`` package) also work, such as
-``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``.
+`amsmath` package) also work, such as
+`\begin{equation}...\end{equation}`, and `\begin{align}...\end{align}`.
 New LaTeX macros may be defined using standard methods,
-such as ``\newcommand``, by placing them anywhere *between math delimiters* in
+such as `\newcommand`, by placing them anywhere _between math delimiters_ in
 a Markdown cell. These definitions are then available throughout the rest of
 the IPython session.
 
-.. seealso::
-
-    `Working with Markdown Cells`_ example notebook
+:::{seealso}
+[Working with Markdown Cells] example notebook
+:::
 
-Raw cells
-~~~~~~~~~
+### Raw cells
 
-*Raw* cells provide a place in which you can write *output* directly.
+_Raw_ cells provide a place in which you can write _output_ directly.
 Raw cells are not evaluated by the notebook.
-When passed through nbconvert_, raw cells arrive in the
+When passed through [nbconvert], raw cells arrive in the
 destination format unmodified. For example, you can type full LaTeX
 into a raw cell, which will only be rendered by LaTeX after conversion by
 nbconvert.
 
-
-Basic workflow
---------------
+## Basic workflow
 
 The normal workflow in a notebook is, then, quite similar to a standard
 IPython session, with the difference that you can edit cells in-place multiple
 times until you obtain the desired results, rather than having to
-rerun separate scripts with the ``%run`` magic command.
-
+rerun separate scripts with the `%run` magic command.
 
 Typically, you will work on a computational problem in pieces, organizing
 related ideas into cells and moving forward once previous parts work
@@ -318,67 +294,61 @@ correctly. This is much more convenient for interactive exploration than
 breaking up a computation into scripts that must be executed together, as was
 previously necessary, especially if parts of them take a long time to run.
 
-To interrupt a calculation which is taking too long, use the :guilabel:`Kernel`,
-:guilabel:`Interrupt` menu option, or the :kbd:`i,i` keyboard shortcut.
+To interrupt a calculation which is taking too long, use the {guilabel}`Kernel`,
+{guilabel}`Interrupt` menu option, or the {kbd}`i,i` keyboard shortcut.
 Similarly, to restart the whole computational process,
-use the :guilabel:`Kernel`, :guilabel:`Restart` menu option or :kbd:`0,0`
+use the {guilabel}`Kernel`, {guilabel}`Restart` menu option or {kbd}`0,0`
 shortcut.
 
-A notebook may be downloaded as a ``.ipynb`` file or converted to a number of
-other formats using the menu option :guilabel:`File`, :guilabel:`Download as`.
+A notebook may be downloaded as a `.ipynb` file or converted to a number of
+other formats using the menu option {guilabel}`File`, {guilabel}`Download as`.
 
-.. seealso::
+:::{seealso}
+[Running Code in the Jupyter Notebook] example notebook
 
-    `Running Code in the Jupyter Notebook`_ example notebook
+[Notebook Basics] example notebook
+:::
 
-    `Notebook Basics`_ example notebook
+(keyboard-shortcuts)=
 
-.. _keyboard-shortcuts:
+### Keyboard shortcuts
 
-Keyboard shortcuts
-~~~~~~~~~~~~~~~~~~
 All actions in the notebook can be performed with the mouse, but keyboard
 shortcuts are also available for the most common ones. The essential shortcuts
 to remember are the following:
 
-* :kbd:`Shift-Enter`:  run cell
-    Execute the current cell, show any output, and jump to the next cell below.
-    If :kbd:`Shift-Enter` is invoked on the last cell, it makes a new cell below.
-    This is equivalent to clicking the :guilabel:`Cell`, :guilabel:`Run` menu
-    item, or the Play button in the toolbar.
+- {kbd}`Shift-Enter`: run cell
+  : Execute the current cell, show any output, and jump to the next cell below.
+  If {kbd}`Shift-Enter` is invoked on the last cell, it makes a new cell below.
+  This is equivalent to clicking the {guilabel}`Cell`, {guilabel}`Run` menu
+  item, or the Play button in the toolbar.
+- {kbd}`Esc`: Command mode
+  : In command mode, you can navigate around the notebook using keyboard shortcuts.
+- {kbd}`Enter`: Edit mode
+  : In edit mode, you can edit text in cells.
 
-* :kbd:`Esc`: Command mode
-    In command mode, you can navigate around the notebook using keyboard shortcuts.
+For the full list of available shortcuts, click {guilabel}`Help`,
+{guilabel}`Keyboard Shortcuts` in the notebook menus.
 
-* :kbd:`Enter`: Edit mode
-    In edit mode, you can edit text in cells.
+## Plotting
 
-For the full list of available shortcuts, click :guilabel:`Help`,
-:guilabel:`Keyboard Shortcuts` in the notebook menus.
-
-Plotting
---------
 One major feature of the Jupyter notebook is the ability to display plots that
 are the output of running code cells. The IPython kernel is designed to work
-seamlessly with the matplotlib_ plotting library to provide this functionality.
+seamlessly with the [matplotlib] plotting library to provide this functionality.
 Specific plotting library integration is a feature of the kernel.
 
-Installing kernels
-------------------
+## Installing kernels
 
 For information on how to install a Python kernel, refer to the
-`IPython install page <https://ipython.org/install.html>`__.
+[IPython install page](https://ipython.org/install.html).
 
-The Jupyter wiki has a long list of `Kernels for other languages
-<https://github.com/jupyter/jupyter/wiki/Jupyter-kernels>`_.
+The Jupyter wiki has a long list of [Kernels for other languages](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels).
 They usually come with instructions on how to make the kernel available
 in the notebook.
 
+(signing-notebooks)=
 
-.. _signing_notebooks:
-
-Trusting Notebooks
-------------------
+## Trusting Notebooks
 
 To prevent untrusted code from executing on users' behalf when notebooks open,
 we store a signature of each trusted notebook.
@@ -393,22 +363,21 @@ load.
 
 If you need to see HTML or Javascript output without re-executing,
 and you are sure the notebook is not malicious, you can tell Jupyter to trust it
-at the command-line with::
+at the command-line with:
 
-    $ jupyter trust mynotebook.ipynb
+```
+$ jupyter trust mynotebook.ipynb
+```
 
-See the `security documentation <https://jupyter-server.readthedocs.io/en/stable/operators/security.html>`__ for more details about the trust mechanism.
+See the [security documentation](https://jupyter-server.readthedocs.io/en/stable/operators/security.html) for more details about the trust mechanism.
 
-
-
-Browser Compatibility
----------------------
+## Browser Compatibility
 
 The Jupyter Notebook aims to support the latest versions of these browsers:
 
-* Chrome
-* Safari
-* Firefox
+- Chrome
+- Safari
+- Firefox
 
 Up to date versions of Opera and Edge may also work, but if they don't, please
 use one of the supported browsers.
@@ -416,4 +385,9 @@ use one of the supported browsers.
 Using Safari with HTTPS and an untrusted certificate is known to not work
 (websockets will fail).
 
+```{eval-rst}
 .. include:: links.txt
+```
+
+[json]: https://en.wikipedia.org/wiki/JSON
+[mathjax]: https://www.mathjax.org/
diff --git a/docs/source/troubleshooting.md b/docs/source/troubleshooting.md
new file mode 100644
index 0000000000..40e25a9938
--- /dev/null
+++ b/docs/source/troubleshooting.md
@@ -0,0 +1,243 @@
+# What to do when things go wrong
+
+First, have a look at the common problems listed below. If you can figure it out
+from these notes, it will be quicker than asking for help.
+
+Check that you have the latest version of any packages that look relevant.
+Unfortunately it's not always easy to figure out what packages are relevant,
+but if there was a bug that's already been fixed,
+it's easy to upgrade and get on with what you wanted to do.
+
+## Jupyter fails to start
+
+- Have you [installed it](https://jupyter.org/install.html)? ;-)
+- If you're using a menu shortcut or Anaconda launcher to start it, try
+  opening a terminal or command prompt and running the command `jupyter notebook`.
+- If it can't find `jupyter`,
+  you may need to configure your `PATH` environment variable.
+  If you don't know what that means, and don't want to find out,
+  just (re)install Anaconda with the default settings,
+  and it should set up PATH correctly.
+- If Jupyter gives an error that it can't find `notebook`,
+  check with pip or conda that the `notebook` package is installed.
+- Try running `jupyter-notebook` (with a hyphen). This should normally be the
+  same as `jupyter notebook` (with a space), but if there's any difference,
+  the version with the hyphen is the 'real' launcher, and the other one wraps
+  that.
+
+## Jupyter doesn't load or doesn't work in the browser
+
+- Try in another browser (e.g. if you normally use Firefox, try with Chrome).
+  This helps pin down where the problem is.
+- Try disabling any browser extensions and/or any Jupyter extensions you have
+  installed.
+- Some internet security software can interfere with Jupyter.
+  If you have security software, try turning it off temporarily,
+  and look in the settings for a more long-term solution.
+- In the address bar, try changing between `localhost` and `127.0.0.1`.
+  They should be the same, but in some cases it makes a difference.
+
+## Jupyter can't start a kernel
+
+Files called _kernel specs_ tell Jupyter how to start different kinds of kernels.
+To see where these are on your system, run `jupyter kernelspec list`:
+
+```
+$ jupyter kernelspec list
+Available kernels:
+  python3      /home/takluyver/.local/lib/python3.6/site-packages/ipykernel/resources
+  bash         /home/takluyver/.local/share/jupyter/kernels/bash
+  ir           /home/takluyver/.local/share/jupyter/kernels/ir
+```
+
+There's a special fallback for the Python kernel:
+if it doesn't find a real kernelspec, but it can import the `ipykernel` package,
+it provides a kernel which will run in the same Python environment as the notebook server.
+A path ending in `ipykernel/resources`, like in the example above,
+is this default kernel.
+The default often does what you want,
+so if the `python3` kernelspec points somewhere else
+and you can't start a Python kernel,
+try deleting or renaming that kernelspec folder to expose the default.
+
+If your problem is with another kernel, not the Python one we maintain,
+you may need to look for support about that kernel.
+
+## Python Environments
+
+Multiple python environments, whether based on Anaconda or Python Virtual environments,
+are often the source of reported issues. In many cases, these issues stem from the
+Notebook server running in one environment, while the kernel and/or its resources,
+derive from another environment. Indicators of this scenario include:
+
+- `import` statements within code cells producing `ImportError` or `ModuleNotFound` exceptions.
+- General kernel startup failures exhibited by nothing happening when attempting
+  to execute a cell.
+
+In these situations, take a close look at your environment structure and ensure all
+packages required by your notebook's code are installed in the correct environment.
+If you need to run the kernel from different environments than your Notebook
+server, check out [IPython's documentation](https://ipython.readthedocs.io/en/stable/install/kernel_install.html#kernels-for-different-environments)
+for using kernels from different environments as this is the recommended approach.
+Anaconda's [nb_conda_kernels](https://github.com/Anaconda-Platform/nb_conda_kernels)
+package might also be an option for you in these scenarios.
+
+Another thing to check is the `kernel.json` file that will be located in the
+aforementioned _kernel specs_ directory identified by running `jupyter kernelspec list`.
+This file will contain an `argv` stanza that includes the actual command to run
+when launching the kernel. Oftentimes, when reinstalling python environments, a previous
+`kernel.json` will reference an python executable from an old or non-existent location.
+As a result, it's always a good idea when encountering kernel startup issues to validate
+the `argv` stanza to ensure all file references exist and are appropriate.
+
+## Windows Systems
+
+Although Jupyter Notebook is primarily developed on the various flavors of the Unix
+operating system it also supports Microsoft
+Windows - which introduces its own set of commonly encountered issues,
+particularly in the areas of security, process management and lower-level libraries.
+
+### pywin32 Issues
+
+The primary package for interacting with Windows' primitives is `pywin32`.
+
+- Issues surrounding the creation of the kernel's communication file utilize
+  `jupyter_core`'s `secure_write()` function. This function ensures a file is
+  created in which only the owner of the file has access. If libraries like `pywin32`
+  are not properly installed, issues can arise when it's necessary to use the native
+  Windows libraries.
+
+  Here's a portion of such a traceback:
+
+  ```
+  File "c:\users\jovyan\python\myenv.venv\lib\site-packages\jupyter_core\paths.py", line 424, in secure_write
+  win32_restrict_file_to_user(fname)
+  File "c:\users\jovyan\python\myenv.venv\lib\site-packages\jupyter_core\paths.py", line 359, in win32_restrict_file_to_user
+  import win32api
+  ImportError: DLL load failed: The specified module could not be found.
+  ```
+
+- As noted earlier, the installation of `pywin32` can be problematic on Windows
+  configurations. When such an issue occurs, you may need to revisit how the environment
+  was setup. Pay careful attention to whether you're running the 32 or 64 bit versions
+  of Windows and be sure to install appropriate packages for that environment.
+
+  Here's a portion of such a traceback:
+
+  ```
+  File "C:\Users\jovyan\AppData\Roaming\Python\Python37\site-packages\jupyter_core\paths.py", line 435, in secure_write
+  win32_restrict_file_to_user(fname)
+  File "C:\Users\jovyan\AppData\Roaming\Python\Python37\site-packages\jupyter_core\paths.py", line 361, in win32_restrict_file_to_user
+  import win32api
+  ImportError: DLL load failed: %1 is not a valid Win32 application
+  ```
+
+#### Resolving pywin32 Issues
+
+> In this case, your `pywin32` module may not be installed correctly and the following
+> should be attempted:
+>
+> ```
+> pip install --upgrade pywin32
+> ```
+>
+> or:
+>
+> ```
+> conda install --force-reinstall pywin32
+> ```
+>
+> followed by:
+>
+> ```
+> python.exe Scripts/pywin32_postinstall.py -install
+> ```
+>
+> where `Scripts` is located in the active Python's installation location.
+
+- Another common failure specific to Windows environments is the location of various
+  python commands. On `*nix` systems, these typically reside in the `bin` directory
+  of the active Python environment. However, on Windows, these tend to reside in the
+  `Scripts` folder - which is a sibling to `bin`. As a result, when encountering
+  kernel startup issues, again, check the `argv` stanza and verify it's pointing to a
+  valid file. You may find that it's pointing in `bin` when `Scripts` is correct, or
+  the referenced file does not include its `.exe` extension - typically resulting in
+  `FileNotFoundError` exceptions.
+
+## This Worked An Hour Ago
+
+The Jupyter stack is very complex and rightfully so, there's a lot going on. On occasion
+you might find the system working perfectly well, then, suddenly, you can't get past a
+certain cell due to `import` failures. In these situations, it's best to ask yourself
+if any new python files were added to your notebook development area.
+
+These issues are usually evident by carefully analyzing the traceback produced in
+the notebook error or the Notebook server's command window. In these cases, you'll typically
+find the Python kernel code (from `IPython` and `ipykernel`) performing _its_ imports
+and notice a file from your Notebook development error included in that traceback followed
+by an `AttributeError`:
+
+```
+File "C:\Users\jovyan\anaconda3\lib\site-packages\ipykernel\connect.py", line 13, in
+from IPython.core.profiledir import ProfileDir
+File "C:\Users\jovyan\anaconda3\lib\site-packages\IPython_init.py", line 55, in
+from .core.application import Application
+...
+File "C:\Users\jovyan\anaconda3\lib\site-packages\ipython_genutils\path.py", line 13, in
+import random
+File "C:\Users\jovyan\Desktop\Notebooks\random.py", line 4, in
+rand_set = random.sample(english_words_lower_set, 12)
+AttributeError: module 'random' has no attribute 'sample'
+```
+
+What has happened is that you have named a file that conflicts with an installed package
+that is used by the kernel software and now introduces a conflict preventing the
+kernel's startup.
+
+**Resolution**: You'll need to rename your file. A best practice would be to prefix or
+_namespace_ your files so as not to conflict with any python package.
+
+## Asking for help
+
+As with any problem, try searching to see if someone has already found an answer.
+If you can't find an existing answer, you can ask questions at:
+
+- The [Jupyter Discourse Forum](https://discourse.jupyter.org/)
+
+- The [jupyter-notebook tag on Stackoverflow](https://stackoverflow.com/questions/tagged/jupyter-notebook)
+
+- Peruse the [jupyter/help repository on Github](https://github.com/jupyter/help) (read-only)
+
+- Or in an issue on another repository, if it's clear which component is
+  responsible. Typical repositories include:
+
+  > - [jupyter_core](https://github.com/jupyter/jupyter_core) - `secure_write()`
+  >   and file path issues
+  > - [jupyter_client](https://github.com/jupyter/jupyter_core) - kernel management
+  >   issues found in Notebook server's command window.
+  > - [IPython](https://github.com/ipython/ipython) and
+  >   [ipykernel](https://github.com/ipython/ipykernel) - kernel runtime issues
+  >   typically found in Notebook server's command window and/or Notebook cell execution.
+
+### Gathering Information
+
+Should you find that your problem warrants that an issue be opened in
+[notebook](https://github.com/jupyter/notebook) please don't forget to provide details
+like the following:
+
+- What error messages do you see (within your notebook and, more importantly, in
+  the Notebook server's command window)?
+- What platform are you on?
+- How did you install Jupyter?
+- What have you tried already?
+
+The `jupyter troubleshoot` command collects a lot of information
+about your installation, which can also be useful.
+
+When providing textual information, it's most helpful if you can _scrape_ the contents
+into the issue rather than providing a screenshot. This enables others to select
+pieces of that content so they can search more efficiently and try to help.
+
+Remember that it's not anyone's job to help you.
+We want Jupyter to work for you,
+but we can't always help everyone individually.
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
deleted file mode 100644
index 84a3739f52..0000000000
--- a/docs/source/troubleshooting.rst
+++ /dev/null
@@ -1,233 +0,0 @@
-What to do when things go wrong
-===============================
-
-First, have a look at the common problems listed below. If you can figure it out
-from these notes, it will be quicker than asking for help.
-
-Check that you have the latest version of any packages that look relevant.
-Unfortunately it's not always easy to figure out what packages are relevant,
-but if there was a bug that's already been fixed,
-it's easy to upgrade and get on with what you wanted to do.
-
-Jupyter fails to start
-----------------------
-
-* Have you `installed it <https://jupyter.org/install.html>`__? ;-)
-* If you're using a menu shortcut or Anaconda launcher to start it, try
-  opening a terminal or command prompt and running the command ``jupyter notebook``.
-* If it can't find ``jupyter``,
-  you may need to configure your ``PATH`` environment variable.
-  If you don't know what that means, and don't want to find out,
-  just (re)install Anaconda with the default settings,
-  and it should set up PATH correctly.
-* If Jupyter gives an error that it can't find ``notebook``,
-  check with pip or conda that the ``notebook`` package is installed.
-* Try running ``jupyter-notebook`` (with a hyphen). This should normally be the
-  same as ``jupyter notebook`` (with a space), but if there's any difference,
-  the version with the hyphen is the 'real' launcher, and the other one wraps
-  that.
-
-Jupyter doesn't load or doesn't work in the browser
----------------------------------------------------
-
-* Try in another browser (e.g. if you normally use Firefox, try with Chrome).
-  This helps pin down where the problem is.
-* Try disabling any browser extensions and/or any Jupyter extensions you have
-  installed.
-* Some internet security software can interfere with Jupyter.
-  If you have security software, try turning it off temporarily,
-  and look in the settings for a more long-term solution.
-* In the address bar, try changing between ``localhost`` and ``127.0.0.1``.
-  They should be the same, but in some cases it makes a difference.
-
-Jupyter can't start a kernel
-----------------------------
-
-Files called *kernel specs* tell Jupyter how to start different kinds of kernels.
-To see where these are on your system, run ``jupyter kernelspec list``::
-
-    $ jupyter kernelspec list
-    Available kernels:
-      python3      /home/takluyver/.local/lib/python3.6/site-packages/ipykernel/resources
-      bash         /home/takluyver/.local/share/jupyter/kernels/bash
-      ir           /home/takluyver/.local/share/jupyter/kernels/ir
-
-There's a special fallback for the Python kernel:
-if it doesn't find a real kernelspec, but it can import the ``ipykernel`` package,
-it provides a kernel which will run in the same Python environment as the notebook server.
-A path ending in ``ipykernel/resources``, like in the example above,
-is this default kernel.
-The default often does what you want,
-so if the ``python3`` kernelspec points somewhere else
-and you can't start a Python kernel,
-try deleting or renaming that kernelspec folder to expose the default.
-
-If your problem is with another kernel, not the Python one we maintain,
-you may need to look for support about that kernel.
-
-Python Environments
--------------------
-Multiple python environments, whether based on Anaconda or Python Virtual environments,
-are often the source of reported issues.  In many cases, these issues stem from the
-Notebook server running in one environment, while the kernel and/or its resources,
-derive from another environment.  Indicators of this scenario include:
-
-* ``import`` statements within code cells producing ``ImportError`` or ``ModuleNotFound`` exceptions.
-* General kernel startup failures exhibited by nothing happening when attempting
-  to execute a cell.
-
-In these situations, take a close look at your environment structure and ensure all
-packages required by your notebook's code are installed in the correct environment.
-If you need to run the kernel from different environments than your Notebook
-server, check out `IPython's documentation <https://ipython.readthedocs.io/en/stable/install/kernel_install.html#kernels-for-different-environments>`_
-for using kernels from different environments as this is the recommended approach.
-Anaconda's `nb_conda_kernels <https://github.com/Anaconda-Platform/nb_conda_kernels>`_
-package might also be an option for you in these scenarios.
-
-Another thing to check is the ``kernel.json`` file that will be located in the
-aforementioned *kernel specs* directory identified by running ``jupyter kernelspec list``.
-This file will contain an ``argv`` stanza that includes the actual command to run
-when launching the kernel.  Oftentimes, when reinstalling python environments, a previous
-``kernel.json`` will reference an python executable from an old or non-existent location.
-As a result, it's always a good idea when encountering kernel startup issues to validate
-the ``argv`` stanza to ensure all file references exist and are appropriate.
-
-Windows Systems
----------------
-Although Jupyter Notebook is primarily developed on the various flavors of the Unix
-operating system it also supports Microsoft
-Windows - which introduces its own set of commonly encountered issues,
-particularly in the areas of security, process management and lower-level libraries.
-
-pywin32 Issues
-^^^^^^^^^^^^^^^^^^
-The primary package for interacting with Windows' primitives is ``pywin32``.
-
-* Issues surrounding the creation of the kernel's communication file utilize
-  ``jupyter_core``'s ``secure_write()`` function.  This function ensures a file is
-  created in which only the owner of the file has access.  If libraries like ``pywin32``
-  are not properly installed, issues can arise when it's necessary to use the native
-  Windows libraries.
-
-  Here's a portion of such a traceback::
-
-    File "c:\users\jovyan\python\myenv.venv\lib\site-packages\jupyter_core\paths.py", line 424, in secure_write
-    win32_restrict_file_to_user(fname)
-    File "c:\users\jovyan\python\myenv.venv\lib\site-packages\jupyter_core\paths.py", line 359, in win32_restrict_file_to_user
-    import win32api
-    ImportError: DLL load failed: The specified module could not be found.
-
-* As noted earlier, the installation of ``pywin32`` can be problematic on Windows
-  configurations.  When such an issue occurs, you may need to revisit how the environment
-  was setup.  Pay careful attention to whether you're running the 32 or 64 bit versions
-  of Windows and be sure to install appropriate packages for that environment.
-
-  Here's a portion of such a traceback::
-
-    File "C:\Users\jovyan\AppData\Roaming\Python\Python37\site-packages\jupyter_core\paths.py", line 435, in secure_write
-    win32_restrict_file_to_user(fname)
-    File "C:\Users\jovyan\AppData\Roaming\Python\Python37\site-packages\jupyter_core\paths.py", line 361, in win32_restrict_file_to_user
-    import win32api
-    ImportError: DLL load failed: %1 is not a valid Win32 application
-
-Resolving pywin32 Issues
-""""""""""""""""""""""""""""
-  In this case, your ``pywin32`` module may not be installed correctly and the following
-  should be attempted:
-  ::
-
-    pip install --upgrade pywin32
-
-  or::
-
-    conda install --force-reinstall pywin32
-
-  followed by::
-
-    python.exe Scripts/pywin32_postinstall.py -install
-
-  where ``Scripts`` is located in the active Python's installation location.
-
-* Another common failure specific to Windows environments is the location of various
-  python commands.  On ``*nix`` systems, these typically reside in the ``bin`` directory
-  of the active Python environment.  However, on Windows, these tend to reside in the
-  ``Scripts`` folder - which is a sibling to ``bin``.  As a result, when encountering
-  kernel startup issues, again, check the ``argv`` stanza and verify it's pointing to a
-  valid file.  You may find that it's pointing in ``bin`` when ``Scripts`` is correct, or
-  the referenced file does not include its ``.exe`` extension - typically resulting in
-  ``FileNotFoundError`` exceptions.
-
-This Worked An Hour Ago
------------------------
-The Jupyter stack is very complex and rightfully so, there's a lot going on.  On occasion
-you might find the system working perfectly well, then, suddenly, you can't get past a
-certain cell due to ``import`` failures.  In these situations, it's best to ask yourself
-if any new python files were added to your notebook development area.
-
-These issues are usually evident by carefully analyzing the traceback produced in
-the notebook error or the Notebook server's command window.  In these cases, you'll typically
-find the Python kernel code (from ``IPython`` and ``ipykernel``) performing *its* imports
-and notice a file from your Notebook development error included in that traceback followed
-by an ``AttributeError``::
-
-    File "C:\Users\jovyan\anaconda3\lib\site-packages\ipykernel\connect.py", line 13, in
-    from IPython.core.profiledir import ProfileDir
-    File "C:\Users\jovyan\anaconda3\lib\site-packages\IPython_init.py", line 55, in
-    from .core.application import Application
-    ...
-    File "C:\Users\jovyan\anaconda3\lib\site-packages\ipython_genutils\path.py", line 13, in
-    import random
-    File "C:\Users\jovyan\Desktop\Notebooks\random.py", line 4, in
-    rand_set = random.sample(english_words_lower_set, 12)
-    AttributeError: module 'random' has no attribute 'sample'
-
-What has happened is that you have named a file that conflicts with an installed package
-that is used by the kernel software and now introduces a conflict preventing the
-kernel's startup.
-
-**Resolution**: You'll need to rename your file.  A best practice would be to prefix or
-*namespace* your files so as not to conflict with any python package.
-
-
-Asking for help
----------------
-
-As with any problem, try searching to see if someone has already found an answer.
-If you can't find an existing answer, you can ask questions at:
-
-* The `Jupyter Discourse Forum <https://discourse.jupyter.org/>`_
-* The `jupyter-notebook tag on Stackoverflow <https://stackoverflow.com/questions/tagged/jupyter-notebook>`_
-* Peruse the `jupyter/help repository on Github <https://github.com/jupyter/help>`_ (read-only)
-* Or in an issue on another repository, if it's clear which component is
-  responsible.  Typical repositories include:
-
-    * `jupyter_core <https://github.com/jupyter/jupyter_core>`_ - ``secure_write()``
-      and file path issues
-    * `jupyter_client <https://github.com/jupyter/jupyter_core>`_ - kernel management
-      issues found in Notebook server's command window.
-    * `IPython <https://github.com/ipython/ipython>`_ and
-      `ipykernel <https://github.com/ipython/ipykernel>`_ - kernel runtime issues
-      typically found in Notebook server's command window and/or Notebook cell execution.
-
-Gathering Information
-^^^^^^^^^^^^^^^^^^^^^
-Should you find that your problem warrants that an issue be opened in
-`notebook <https://github.com/jupyter/notebook>`_ please don't forget to provide details
-like the following:
-
-* What error messages do you see (within your notebook and, more importantly, in
-  the Notebook server's command window)?
-* What platform are you on?
-* How did you install Jupyter?
-* What have you tried already?
-
-The ``jupyter troubleshoot`` command collects a lot of information
-about your installation, which can also be useful.
-
-When providing textual information, it's most helpful if you can *scrape* the contents
-into the issue rather than providing a screenshot.  This enables others to select
-pieces of that content so they can search more efficiently and try to help.
-
-Remember that it's not anyone's job to help you.
-We want Jupyter to work for you,
-but we can't always help everyone individually.
diff --git a/docs/source/ui_components.rst b/docs/source/ui_components.md
similarity index 60%
rename from docs/source/ui_components.rst
rename to docs/source/ui_components.md
index b5fc506dfe..45404c3d32 100644
--- a/docs/source/ui_components.rst
+++ b/docs/source/ui_components.md
@@ -1,5 +1,4 @@
-User interface components
-=========================
+# User interface components
 
 When opening bug reports or sending emails to the Jupyter mailing list, it is
 useful to know the names of different UI components so that other developers
@@ -7,44 +6,47 @@ and users have an easier time helping you diagnose your problems. This section
 will familiarize you with the names of UI elements within the Notebook and the
 different Notebook modes.
 
-Notebook Dashboard
--------------------
+## Notebook Dashboard
 
-When you launch ``jupyter notebook`` the first page that you encounter is the
+When you launch `jupyter notebook` the first page that you encounter is the
 Notebook Dashboard.
 
-.. image:: ./_static/images/jupyter-notebook-dashboard.png
+```{image} ./_static/images/jupyter-notebook-dashboard.png
 
-Notebook Editor
----------------
+```
+
+## Notebook Editor
 
 Once you've selected a Notebook to edit, the Notebook will open in the Notebook
 Editor.
 
-.. image:: ./_static/images/jupyter-notebook-default.png
+```{image} ./_static/images/jupyter-notebook-default.png
+
+```
 
-Interactive User Interface Tour of the Notebook
------------------------------------------------
+## Interactive User Interface Tour of the Notebook
 
 If you would like to learn more about the specific elements within the Notebook
-Editor, you can go through the user interface tour by selecting *Help* in the
-menubar then selecting *User Interface Tour*.
+Editor, you can go through the user interface tour by selecting _Help_ in the
+menubar then selecting _User Interface Tour_.
 
-Edit Mode and Notebook Editor
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Edit Mode and Notebook Editor
 
 When a cell is in edit mode, the Cell Mode Indicator will change to reflect
 the cell's state. This state is indicated by a small pencil icon on the
 top right of the interface. When the cell is in command mode, there is no
 icon in that location.
 
-.. image:: ./_static/images/jupyter-notebook-edit.png
+```{image} ./_static/images/jupyter-notebook-edit.png
 
-File Editor
------------
+```
+
+## File Editor
 
 Now let's say that you've chosen to open a Markdown file instead of a Notebook
 file whilst in the Notebook Dashboard. If so, the file will be opened in the
 File Editor.
 
-.. image:: ./_static/images/jupyter-file-editor.png
+```{image} ./_static/images/jupyter-file-editor.png
+
+```
diff --git a/docs/source/user-documentation.md b/docs/source/user-documentation.md
new file mode 100644
index 0000000000..42dfe3922c
--- /dev/null
+++ b/docs/source/user-documentation.md
@@ -0,0 +1,11 @@
+# User Documentation
+
+```{toctree}
+:maxdepth: 2
+
+notebook
+ui_components
+examples/Notebook/examples_index.rst
+troubleshooting
+changelog
+```
diff --git a/docs/source/user-documentation.rst b/docs/source/user-documentation.rst
deleted file mode 100644
index 0036bc63fd..0000000000
--- a/docs/source/user-documentation.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-==================
-User Documentation
-==================
-
-.. toctree::
-   :maxdepth: 2
-
-   notebook
-   ui_components
-   examples/Notebook/examples_index.rst
-   troubleshooting
-   changelog