Suppresses header check inside frontmatter (#14203)

* Suppresses header check inside frontmatter

* Updates frontmatter detection, updates test cases

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Does frontmatter check before loop, adds test case

* Lint issues

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

packages/toc/src/utils/markdown.ts

@@ -65,15 +65,35 @@ export function getHeadings(text: string): IMarkdownHeading[] {
   // Iterate over the lines to get the header level and text for each line:
   const headings = new Array<IMarkdownHeading>();
   let isCodeBlock;
-  for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+  let lineIdx = 0;
+
+  // Don't check for Markdown headings if in a YAML frontmatter block.
+  // We can only start a frontmatter block on the first line of the file.
+  // At other positions in a markdown file, '---' represents a horizontal rule.
+  if (lines[lineIdx] === '---') {
+    // Search for another '---' and treat that as the end of the frontmatter.
+    // If we don't find one, treat the file as containing no frontmatter.
+    for (
+      let frontmatterEndLineIdx = lineIdx + 1;
+      frontmatterEndLineIdx < lines.length;
+      frontmatterEndLineIdx++
+    ) {
+      if (lines[frontmatterEndLineIdx] === '---') {
+        lineIdx = frontmatterEndLineIdx + 1;
+        break;
+      }
+    }
+  }
+
+  for (; lineIdx < lines.length; lineIdx++) {
     const line = lines[lineIdx];
 
     if (line === '') {
       // Bail early
       continue;
     }
 
-    // Don't check for Markdown headings if in a code block:
+    // Don't check for Markdown headings if in a code block
     if (line.startsWith('```')) {
       isCodeBlock = !isCodeBlock;
     }

packages/toc/test/markdown.spec.ts

@@ -193,7 +193,96 @@ describe('TableOfContentsUtils', () => {
         ['\nTitle\n\n--', []],
         ['```\n# Title\n```', []],
         ['```\nTitle\n--\n```', []],
-        ['```\n<h1>Title</h1>\n```', []]
+        ['```\n<h1>Title</h1>\n```', []],
+        ['---\n<h1>Title</h1>\n---', []],
+        ['---\n# Title\n---', []],
+        [
+          `---
+<h1>Ignored</h1>
+---
+# Title`,
+          [
+            {
+              text: 'Title',
+              level: 1,
+              line: 3,
+              raw: '# Title',
+              prefix: '1. ',
+              skip: false
+            }
+          ]
+        ],
+        [
+          `---
+front: matter
+---
+
+# Header
+
+> this has whitespace _after_`,
+          [
+            {
+              text: 'Header',
+              level: 1,
+              line: 4,
+              raw: '# Header',
+              prefix: '1. ',
+              skip: false
+            }
+          ]
+        ],
+        [
+          `---
+front: matter
+---
+# Header
+
+---
+# Header between horizontal rules
+---
+
+# Header after horizontal rules`,
+          [
+            {
+              text: 'Header',
+              level: 1,
+              line: 3,
+              raw: '# Header',
+              prefix: '1. ',
+              skip: false
+            },
+            {
+              text: 'Header between horizontal rules',
+              level: 1,
+              line: 6,
+              raw: '# Header between horizontal rules',
+              prefix: '2. ',
+              skip: false
+            },
+            {
+              text: 'Header after horizontal rules',
+              level: 1,
+              line: 9,
+              raw: '# Header after horizontal rules',
+              prefix: '3. ',
+              skip: false
+            }
+          ]
+        ],
+        [
+          `---
+# Header`,
+          [
+            {
+              text: 'Header',
+              level: 1,
+              line: 1,
+              raw: '# Header',
+              prefix: '1. ',
+              skip: false
+            }
+          ]
+        ]
       ])('should extract headings from %s', (src, headers) => {
         const headings = TableOfContentsUtils.filterHeadings(
           TableOfContentsUtils.Markdown.getHeadings(src),