From 641ca6f3d8cd8fb0ae24e4f77b2e62a44a65e53b Mon Sep 17 00:00:00 2001
From: iBug <git@ibugone.com>
Date: Mon, 29 Mar 2021 20:13:27 +0800
Subject: [PATCH] Add note on TOC heading level issue (#2902)

https://github.com/mmistakes/minimal-mistakes/issues/2892#issuecomment-809220952
---
 .gitattributes           | 14 +++++++++-----
 docs/_docs/10-layouts.md | 25 +++++++++++++++++++++++++
 docs/_docs/14-helpers.md | 25 +++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/.gitattributes b/.gitattributes
index a12b5fb4..4d536e4a 100644
--- a/.gitattributes
+++ b/.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
diff --git a/docs/_docs/10-layouts.md b/docs/_docs/10-layouts.md
index 04831882..acb7e098 100644
--- a/docs/_docs/10-layouts.md
+++ b/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.
diff --git a/docs/_docs/14-helpers.md b/docs/_docs/14-helpers.md
index 59ac0171..8ae40399 100644
--- a/docs/_docs/14-helpers.md
+++ b/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.