From 1eeb981b0fb16a4b3f22f768611572cfac865c1c Mon Sep 17 00:00:00 2001
From: Matthias Geier <Matthias.Geier@gmail.com>
Date: Sat, 3 Feb 2024 12:02:35 +0100
Subject: [PATCH] DOC: add a notebook with spaces in its file name

---
 doc/a notebook name with spaces.ipynb | 53 +++++++++++++++++++++++++++
 doc/markdown-cells.ipynb              |  8 ++++
 doc/subdir/toctree.ipynb              |  7 +++-
 3 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 doc/a notebook name with spaces.ipynb

diff --git a/doc/a notebook name with spaces.ipynb b/doc/a notebook name with spaces.ipynb
new file mode 100644
index 00000000..85ccc864
--- /dev/null
+++ b/doc/a notebook name with spaces.ipynb	
@@ -0,0 +1,53 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "source": [
+    "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# A Notebook With Spaces in Its File Name\n",
+    "\n",
+    "File names with spaces often need special treatment,\n",
+    "so it's probably better to avoid them.\n",
+    "\n",
+    "In Markdown links,\n",
+    "the spaces have to be replaced by `%10`,\n",
+    "as shown in\n",
+    "[the section about links](markdown-cells.ipynb#Links-to-Other-Notebooks).\n",
+    "\n",
+    "This is also relevant when using the\n",
+    "`nbsphinx-toctree` cell tag, as shown\n",
+    "[here](subdir/toctree.ipynb)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/doc/markdown-cells.ipynb b/doc/markdown-cells.ipynb
index d7d906b5..b3442b16 100644
--- a/doc/markdown-cells.ipynb
+++ b/doc/markdown-cells.ipynb
@@ -544,6 +544,14 @@
     "[mylink]: subdir/a-notebook-in-a-subdir.ipynb\n",
     "```\n",
     "\n",
+    "When a notebook file name contains spaces,\n",
+    "they have to be replaced by `%10`, like in\n",
+    "[this link](../a%10notebook%10name%10with%10spaces.ipynb):\n",
+    "\n",
+    "```\n",
+    "[this link](../a%10notebook%10name%10with%10spaces.ipynb)\n",
+    "```\n",
+    "\n",
     "Links to sub-sections are also possible, e.g.\n",
     "[this subsection](subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section).\n",
     "\n",
diff --git a/doc/subdir/toctree.ipynb b/doc/subdir/toctree.ipynb
index 1fd5009d..7ab44c96 100644
--- a/doc/subdir/toctree.ipynb
+++ b/doc/subdir/toctree.ipynb
@@ -94,7 +94,10 @@
     "\n",
     "</div>\n",
     "\n",
-    "The following cell is tagged with `nbsphinx-toctree` and contains a link to the notebook [yet-another.ipynb](../yet-another.ipynb) and an external link (which will only be visible in the HTML output).\n",
+    "The following cell is tagged with `nbsphinx-toctree` and contains a link to the notebooks\n",
+    "[yet-another.ipynb](../yet-another.ipynb) and\n",
+    "[a notebook name with spaces.ipynb](../a%10notebook%10name%10with%10spaces.ipynb)\n",
+    "and an external link (which will only be visible in the HTML output).\n",
     "It also contains a section title which will be used as `toctree` caption\n",
     "(which also will only be visible in the HTML output)."
    ]
@@ -113,6 +116,8 @@
     "\n",
     "[A Notebook that's just a \"toctree\" Target](../yet-another.ipynb)\n",
     "\n",
+    "[A Notebook With Spaces in Its File Name](../a%10notebook%10name%10with%10spaces.ipynb)\n",
+    "\n",
     "[An External Link (HTML only)](https://nbsphinx.readthedocs.io/)\n",
     "\n",
     "Only the first section title (optional) and links to other source files (and external links) are used,\n",