Fix table of contents generation for release notes (#1000)

- [x] fixed typo: `table-of-content` in the backreference
- [x] missing sanitization of `_`,`+`,`.`,`?` etc.
- [x] handling the confusion of h1 `#` and comment `#`

Author: sholderbach

make_release/release-note/notes.nu

@@ -44,10 +44,18 @@ export def pr-table [] {
     | to md
 }
 
-const toc = '[[toc](#table-of-content)]'
+const toc = '[[toc](#table-of-contents)]'
 
 # Generate and write the table of contents to a release notes file
 export def write-toc [file: path] {
+    let known_h1s = [
+        "# Highlights and themes of this release",
+        "# Changes",
+        "# Notes for plugin developers",
+        "# Hall of fame",
+        "# Full changelog",
+    ]
+
     let lines = open $file | lines | each { str trim -r }
 
     let content_start = 2 + (
@@ -65,11 +73,32 @@ export def write-toc [file: path] {
         | insert level {
             get line | split chars | take while { $in == '#' } | length
         }
+        | insert nocomment {
+            # We assume that comments only have one `#`
+            if ($in.level != 1) {
+                return true
+            }
+            let line = $in.line
+
+            # Try to use the whitelist first
+            if ($known_h1s | any {|| $line =~ $in}) {
+                return true
+            }
+
+            # We don't know so let's ask
+            let user = ([Ignore Accept] |
+                input list $"Is this a code comment or a markdown h1 heading:(char nl)(ansi blue)($line)(ansi reset)(char nl)Choose if we include it in the TOC!")
+            match $user {
+                "Accept" => {true}
+                "Ignore" => {false}
+            }
+
+        }
     )
 
     let table_of_contents = (
         $data
-        | where level in 1..=3
+        | where level in 1..=3 and nocomment == true
         | each {|header|
             let indent = '- ' | fill -w ($header.level * 2) -a right
 
@@ -82,17 +111,16 @@ export def write-toc [file: path] {
 
             let link = (
                 $text
-                | str replace -a '`' ''
-                | str replace -a ' ' '-'
-                | str replace -a -r '--+' '-'
+                | str downcase
+                | str kebab-case
             )
 
             $"($indent)[_($text)_]\(#($link)-toc\)"
         }
     )
 
     let content = $data | each {
-        if $in.level in 1..=3 and not ($in.line ends-with $toc) {
+        if $in.level in 1..=3 and not ($in.line ends-with $toc) and $in.nocomment {
             $'($in.line) ($toc)'
         } else {
             $in.line