Add note on TOC heading level issue (mmistakes#2902)

mmistakes#2892 (comment)

Author: iBug

.gitattributes

@@ -1,6 +1,10 @@
-assets/fonts/* linguist-vendored
-assets/js/main.min.js linguist-vendored
-assets/js/lunr/* linguist-vendored
-assets/js/plugins/* linguist-vendored
-assets/js/vendor/* linguist-vendored
+assets/fonts/*                  linguist-vendored
+assets/js/main.min.js           linguist-vendored
+assets/js/lunr/*                linguist-vendored
+assets/js/plugins/*             linguist-vendored
+assets/js/vendor/*              linguist-vendored
 _sass/minimal-mistakes/vendor/* linguist-vendored
+CHANGELOG.md                    text merge=union
+docs/_docs/18-history.md        text merge=union
+
+*.md                            text

docs/_docs/10-layouts.md

@@ -141,6 +141,31 @@ toc_icon: "cog"
 ---
 ```
 
+{% capture notice-text %}
+**Note:** You need to use contiguous levels of headings for the TOC to generate properly. For example:
+
+```markdown
+Good headings:
+
+# Heading
+## Heading
+### Heading
+### Heading
+# Heading
+## Heading
+
+Bad headings:
+
+# Heading
+### Heading (skipped H2)
+##### Heading (skipped H4)
+```
+{% endcapture %}
+
+<div class="notice--warning">
+  {{ notice-text | markdownify }}
+</div>
+
 ## Archive layout
 
 Essentially the same as `single` with markup adjustments and some modules removed.

docs/_docs/14-helpers.md

@@ -295,6 +295,31 @@ toc_icon: "cog"
 **Note:** using both methods will have unintended results. Be sure to remove `{% raw %}{% include toc %}{% endraw %}` placed table of contents from your content when using `toc: true`.
 {: .notice--warning }
 
+{% capture notice-text %}
+**Note:** You need to use contiguous levels of headings for the TOC to generate properly. For example:
+
+```markdown
+Good headings:
+
+# Heading
+## Heading
+### Heading
+### Heading
+# Heading
+## Heading
+
+Bad headings:
+
+# Heading
+### Heading (skipped H2)
+##### Heading (skipped H4)
+```
+{% endcapture %}
+
+<div class="notice--warning">
+  {{ notice-text | markdownify }}
+</div>
+
 ### Enabled via `toc` include (deprecated)
 
 To include a Kramdown [auto-generated table of contents](https://kramdown.gettalong.org/converter/html.html#toc) for posts and pages, add the following helper to your content.