diff --git a/docs/agents.md b/docs/agents.md
index 0009564d..56f9dcc2 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -93,16 +93,6 @@ _(This example is complete, it can be run "as is")_
 
 You can also pass messages from previous runs to continue a conversation or provide context, as described in [Messages and Chat History](message-history.md).
 
-!!! note "jupyter notebooks"
-    If you're running `pydantic-ai` in a jupyter notebook, you might consider using [`nest-asyncio`](https://pypi.org/project/nest-asyncio/)
-    to manage conflicts between event loops that occur between jupyter's event loops and `pydantic-ai`'s.
-
-    Before you execute any agent runs, do the following:
-    ```python {test="skip" lint="skip"}
-    import nest_asyncio
-
-    nest_asyncio.apply()
-    ```
 
 ### Additional Configuration
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 00000000..bc14834c
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,16 @@
+# Troubleshooting
+
+Common/known issues are shown below with associated solutions.
+
+## Jupyter Notebooks
+
+If you're running `pydantic-ai` in a jupyter notebook, you might consider using [`nest-asyncio`](https://pypi.org/project/nest-asyncio/)
+to manage conflicts between event loops that occur between Jupyter's event loops and `pydantic-ai`'s.
+
+Before you execute any agent runs, do the following:
+
+```python {test="skip" lint="skip"}
+import nest_asyncio
+
+nest_asyncio.apply()
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index e60e3a97..6fc07b39 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,6 +14,7 @@ nav:
   - install.md
   - help.md
   - contributing.md
+  - troubleshooting.md
   - Documentation:
     - agents.md
     - models.md