Some quality-of-life enhancements to toc.py CLI script

tutorial/tests/toc_fixture.ipynb

@@ -0,0 +1,189 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "[TOC]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "# Introduction\n",
+    "\n",
+    "This notebook is a fixture for testing `toc.py`. It exercises heading detection,\n",
+    "code block skipping, anchor generation, and edge cases.\n",
+    "\n",
+    "## Why this matters\n",
+    "\n",
+    "The TOC generator must correctly distinguish real Markdown headings from `#` characters\n",
+    "that appear inside fenced code blocks."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
+   "source": [
+    "## Code Blocks with `#` Comments\n",
+    "\n",
+    "The lines below are inside a fenced Python block. They must **not** appear in the TOC.\n",
+    "\n",
+    "```python\n",
+    "# This looks like a heading but is a comment\n",
+    "## So does this\n",
+    "### And this\n",
+    "x = 1  # inline comment\n",
+    "print(x)\n",
+    "```\n",
+    "\n",
+    "This paragraph is after the closing fence — headings here are real again.\n",
+    "\n",
+    "### Real Heading After a Code Block\n",
+    "\n",
+    "This heading immediately follows a closing fence and must be captured."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3",
+   "metadata": {},
+   "source": [
+    "## Fences With Language Specifiers\n",
+    "\n",
+    "Verify that fences with a language tag (` ```bash `, ` ```python `, ` ```text `) still\n",
+    "toggle the code-block state correctly.\n",
+    "\n",
+    "```bash\n",
+    "# bash comment — not a heading\n",
+    "echo \"hello world\"\n",
+    "```\n",
+    "\n",
+    "```python\n",
+    "# another comment — not a heading\n",
+    "print(\"world\")\n",
+    "```\n",
+    "\n",
+    "### Heading Between Two Code Blocks\n",
+    "\n",
+    "This heading sits between two code blocks and must be captured.\n",
+    "\n",
+    "```text\n",
+    "# text block comment — not a heading\n",
+    "```\n",
+    "\n",
+    "### Heading After the Third Block\n",
+    "\n",
+    "Three code blocks closed — heading detection must still be active."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "## Anchor Generation Edge Cases\n",
+    "\n",
+    "### Heading with `inline code` in backticks\n",
+    "\n",
+    "The anchor should strip backtick characters and produce `heading-with-inline-code-in-backticks`.\n",
+    "\n",
+    "### Special Characters: Hello, World!\n",
+    "\n",
+    "Commas, exclamation marks, and colons must be stripped from anchors.\n",
+    "\n",
+    "### Hyphens-are-preserved and Spaces Become Hyphens\n",
+    "\n",
+    "Hyphens that are already in the heading text should survive into the anchor."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5",
+   "metadata": {},
+   "source": [
+    "## Non-Heading `#` Patterns\n",
+    "\n",
+    "The following lines must **not** produce TOC entries:\n",
+    "\n",
+    "#notaheading (no space after `#`)\n",
+    "\n",
+    "    # indented with spaces (indented code block style)\n",
+    "\n",
+    "Some prose with a `#hashtag` inside a sentence."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# This is a Python code cell, not a markdown cell.\n",
+    "# Its content must be completely ignored by the TOC generator.\n",
+    "\n",
+    "## Also not a heading\n",
+    "print('hello')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7",
+   "metadata": {},
+   "source": [
+    "## Cell Splitting\n",
+    "\n",
+    "This cell intentionally contains **two headings** to test `--split-cells`.\n",
+    "Without splitting, the TOC link for the second heading below will not work in\n",
+    "Jupyter because only the first heading in a cell receives a working anchor.\n",
+    "\n",
+    "### Second Heading in the Same Cell\n",
+    "\n",
+    "With `--split-cells`, this cell is rewritten into two separate cells before\n",
+    "the TOC is generated, so both anchor links work."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "## Deep Nesting\n",
+    "\n",
+    "### Level Three\n",
+    "\n",
+    "#### Level Four\n",
+    "\n",
+    "##### Level Five\n",
+    "\n",
+    "Nesting beyond h2 tests that the indentation in the generated TOC list scales with level."
+   ]
+  }
+ ],
+ "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.12.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}