|
@@ -460,7 +460,7 @@
|
|
|
"cell_type": "markdown",
|
|
|
"metadata": {},
|
|
|
"source": [
|
|
|
- "The ToC extension also finds Markdown sections which are programmatically generated..."
|
|
|
+ "The ToC extension also finds Markdown sections which are programmatically generated; however, users are **strongly** encouraged **not** to generate section headings (see **notes** below)..."
|
|
|
]
|
|
|
},
|
|
|
{
|
|
@@ -566,7 +566,7 @@
|
|
|
"data": {
|
|
|
"text/markdown": [
|
|
|
"\n",
|
|
|
- "## Programmatic Output (split)\n",
|
|
|
+ "## Programmatic Output (mixed precedence)\n",
|
|
|
"\n",
|
|
|
"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n",
|
|
|
"\n"
|
|
@@ -590,7 +590,7 @@
|
|
|
"\"\"\"))\n",
|
|
|
"\n",
|
|
|
"display(Markdown(\"\"\"\n",
|
|
|
- "## Programmatic Output (split)\n",
|
|
|
+ "## Programmatic Output (mixed precedence)\n",
|
|
|
"\n",
|
|
|
"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n",
|
|
|
"\n",
|
|
@@ -773,6 +773,179 @@
|
|
|
"display(JSON([4,5,6]))"
|
|
|
]
|
|
|
},
|
|
|
+ {
|
|
|
+ "cell_type": "markdown",
|
|
|
+ "metadata": {},
|
|
|
+ "source": [
|
|
|
+ "## Programmatic Output (recommended)"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "markdown",
|
|
|
+ "metadata": {},
|
|
|
+ "source": [
|
|
|
+ "When programmatically generating Markdown (e.g., for variable interpolation), the following approach is recommended. Hardcode section headings..."
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "markdown",
|
|
|
+ "metadata": {},
|
|
|
+ "source": [
|
|
|
+ "### Subsection"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "markdown",
|
|
|
+ "metadata": {},
|
|
|
+ "source": [
|
|
|
+ "...and then generate section content..."
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "code",
|
|
|
+ "execution_count": 20,
|
|
|
+ "metadata": {
|
|
|
+ "jupyter": {
|
|
|
+ "source_hidden": true
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "outputs": [
|
|
|
+ {
|
|
|
+ "data": {
|
|
|
+ "text/markdown": [
|
|
|
+ "\n",
|
|
|
+ "Lorem ipsum dolor sit amet **3.14**, consectetur adipiscing elit **6.28**, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n"
|
|
|
+ ],
|
|
|
+ "text/plain": [
|
|
|
+ "<IPython.core.display.Markdown object>"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ "metadata": {},
|
|
|
+ "output_type": "display_data"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "source": [
|
|
|
+ "from IPython.display import Markdown, display\n",
|
|
|
+ "\n",
|
|
|
+ "display(Markdown(\"\"\"\n",
|
|
|
+ "Lorem ipsum dolor sit amet **{}**, consectetur adipiscing elit **{}**, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n",
|
|
|
+ "\"\"\".format(3.14, 6.28)))"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "markdown",
|
|
|
+ "metadata": {},
|
|
|
+ "source": [
|
|
|
+ "#### Subsubsection"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "code",
|
|
|
+ "execution_count": 21,
|
|
|
+ "metadata": {
|
|
|
+ "jupyter": {
|
|
|
+ "source_hidden": true
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "outputs": [
|
|
|
+ {
|
|
|
+ "data": {
|
|
|
+ "text/markdown": [
|
|
|
+ "\n",
|
|
|
+ "Lorem ipsum dolor sit amet **3.14**, consectetur adipiscing elit **6.28**, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n"
|
|
|
+ ],
|
|
|
+ "text/plain": [
|
|
|
+ "<IPython.core.display.Markdown object>"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ "metadata": {},
|
|
|
+ "output_type": "display_data"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "source": [
|
|
|
+ "from IPython.display import Markdown, display\n",
|
|
|
+ "\n",
|
|
|
+ "display(Markdown(\"\"\"\n",
|
|
|
+ "Lorem ipsum dolor sit amet **{}**, consectetur adipiscing elit **{}**, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n",
|
|
|
+ "\"\"\".format(3.14, 6.28)))"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "markdown",
|
|
|
+ "metadata": {},
|
|
|
+ "source": [
|
|
|
+ "### Subsection"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "code",
|
|
|
+ "execution_count": 22,
|
|
|
+ "metadata": {
|
|
|
+ "jupyter": {
|
|
|
+ "source_hidden": true
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "outputs": [
|
|
|
+ {
|
|
|
+ "data": {
|
|
|
+ "text/markdown": [
|
|
|
+ "\n",
|
|
|
+ "Lorem ipsum dolor sit amet **3.14**, consectetur adipiscing elit **6.28**, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n"
|
|
|
+ ],
|
|
|
+ "text/plain": [
|
|
|
+ "<IPython.core.display.Markdown object>"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ "metadata": {},
|
|
|
+ "output_type": "display_data"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "source": [
|
|
|
+ "from IPython.display import Markdown, display\n",
|
|
|
+ "\n",
|
|
|
+ "display(Markdown(\"\"\"\n",
|
|
|
+ "Lorem ipsum dolor sit amet **{}**, consectetur adipiscing elit **{}**, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n",
|
|
|
+ "\"\"\".format(3.14, 6.28)))"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "markdown",
|
|
|
+ "metadata": {},
|
|
|
+ "source": [
|
|
|
+ "#### Subsubsection"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "cell_type": "code",
|
|
|
+ "execution_count": 23,
|
|
|
+ "metadata": {
|
|
|
+ "jupyter": {
|
|
|
+ "source_hidden": true
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "outputs": [
|
|
|
+ {
|
|
|
+ "data": {
|
|
|
+ "text/markdown": [
|
|
|
+ "\n",
|
|
|
+ "Lorem ipsum dolor sit amet **3.14**, consectetur adipiscing elit **6.28**, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n"
|
|
|
+ ],
|
|
|
+ "text/plain": [
|
|
|
+ "<IPython.core.display.Markdown object>"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ "metadata": {},
|
|
|
+ "output_type": "display_data"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "source": [
|
|
|
+ "from IPython.display import Markdown, display\n",
|
|
|
+ "\n",
|
|
|
+ "display(Markdown(\"\"\"\n",
|
|
|
+ "Lorem ipsum dolor sit amet **{}**, consectetur adipiscing elit **{}**, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n",
|
|
|
+ "\"\"\".format(3.14, 6.28)))"
|
|
|
+ ]
|
|
|
+ },
|
|
|
{
|
|
|
"cell_type": "markdown",
|
|
|
"metadata": {},
|
|
@@ -780,7 +953,9 @@
|
|
|
"## Notes\n",
|
|
|
"\n",
|
|
|
"- Markdown cells containing multiple \"sections\" only show as the first section in the ToC. Accordingly, users should add a **new** Markdown cell for **each** section.\n",
|
|
|
- "- The ToC extension **does** detect multiple \"sections\" when those sections are generated by code cells. However, **only** the first section is \"collapsible\". Accordingly, users wanting to programmatically generate Markdown sections should only output **one** display element per code cell in order to preserve consistent collapse behavior."
|
|
|
+ "- The ToC extension **does** detect multiple \"sections\" when those sections are generated by code cells. However, users are likely to run into buggy ToC behavior when doing so. Users are strongly encouraged to **avoid** using code cells to generate section headings.\n",
|
|
|
+ "\n",
|
|
|
+ " Instead, users should hardcode each section heading and only generate Markdown output for content **requiring** variable interpolation."
|
|
|
]
|
|
|
},
|
|
|
{
|