Add note on TOC heading level issue (#2902)

https://github.com/mmistakes/minimal-mistakes/issues/2892#issuecomment-809220952
2021-03-29 20:13:27 +08:00
parent 3d3cb58a2e
commit 641ca6f3d8
3 changed files with 59 additions and 5 deletions
--- 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.