Document content page TOC controls

Author: vahidzee

pages/user-guide/extensions/02-markdown.yml

@@ -74,6 +74,41 @@ frontmatter:
     - `nav`: override or disable the inherited navigation.
     - `footer`: override or disable the inherited footer.
     - `comments`: page-level comments configuration when `webifier.comments` is enabled.
+    - `toc`: enable or disable the generated table of contents for this page.
+    - `content_pages`: page-level content-page controls such as `toc` and `cleanup`.
+
+toc_controls:
+  label: Table of Contents
+  content: |
+    Markdown content pages get a generated collapsible table of contents by
+    default when they have enough headings. The TOC is built from `h1` through
+    `h4` headings after Markdown is rendered.
+
+    Disable it for one Markdown page:
+
+    ```text
+    ---
+    title: Short Note
+    toc: false
+    ---
+
+    # Short Note
+    ```
+
+    Or use the more explicit content-page block when you want to group related
+    controls:
+
+    ```text
+    ---
+    title: Course Notes
+    content_pages:
+      toc: true
+      cleanup: true
+    ---
+    ```
+
+    Site-wide defaults live under `content_pages` in the normal Webifier config.
+    Page front matter wins over the site default.
 
 linking:
   label: Typed Links

pages/user-guide/extensions/03-notebook.yml

@@ -70,6 +70,8 @@ yaml_preface:
     - `nav`: override or disable inherited navigation.
     - `footer`: override or disable inherited footer.
     - `comments`: page-level comments settings when comments are enabled.
+    - `toc`: enable or disable the generated table of contents for this notebook page.
+    - `colab`: enable or disable the Colab badge for this notebook page.
 
 linking:
   label: Link a Notebook
@@ -96,11 +98,29 @@ colab:
     If Webifier is run with a repository name, notebook pages can include a
     Google Colab URL pointing to the source notebook in the repository. The
     standard bundled assets include a small Colab badge image for this workflow.
+    Colab links are enabled by default for notebooks when `--repo-full-name` is
+    available.
 
     ```bash
     webify --repo-full-name owner/repo --baseurl /repo
     ```
 
+    Disable the badge for one notebook in the first Markdown cell:
+
+    ```markdown
+    ---
+    title: Local-only Notebook
+    colab: false
+    ---
+    ```
+
+    Or set the site-wide notebook default:
+
+    ```yaml
+    notebook:
+      colab: false
+    ```
+
 assets_and_outputs:
   label: Assets and Outputs
   content: |
@@ -119,10 +139,31 @@ toc_and_polish:
   label: Table of Contents and Page Polish
   content: |
     The standard content page can build a collapsible table of contents from
-    headings in notebook Markdown cells. That works best when notebooks use
+    headings in notebook Markdown cells. Notebook content pages get this TOC by
+    default when they have enough headings. That works best when notebooks use
     normal heading levels and do not also contain a hand-written table of
     contents cell.
 
+    Disable it for one notebook in the first Markdown cell:
+
+    ```markdown
+    ---
+    title: Tiny Notebook
+    toc: false
+    ---
+    ```
+
+    Or use explicit content-page controls:
+
+    ```markdown
+    ---
+    title: Tiny Notebook
+    content_pages:
+      toc: true
+      cleanup: true
+    ---
+    ```
+
     Recommended notebook cleanup before publishing:
 
     - Put metadata in the first Markdown cell as YAML front matter.

pages/user-guide/extensions/examples/tiny-markdown.md

@@ -1,5 +1,6 @@
 ---
 title: Tiny Markdown Example
+toc: true
 ---
 
 # Tiny Markdown Example
@@ -9,6 +10,18 @@ This file is rendered by linking to it with `md=...`.
 Markdown files can carry YAML front matter for page-level metadata, then normal
 Markdown content below it.
 
+## Discovery
+
 - Webifier discovers the link.
 - Webifier creates a sibling HTML page.
 - The generated page shares the site shell, theme, navigation, and footer.
+
+## Page Controls
+
+The front matter at the top of this file sets `toc: true`, so the generated
+page gets a collapsible table of contents when enough headings are present.
+
+## Content
+
+The rest of the file is normal Markdown. You can use headings, lists, links,
+tables, math, code blocks, and inline HTML when you need it.