diff --git a/docs/dashboards.md b/docs/dashboards.md
index 851f4d4f..be14575d 100644
--- a/docs/dashboards.md
+++ b/docs/dashboards.md
@@ -199,8 +199,17 @@ entities.
 
 Markdown files are used to define text widgets that can populate a dashboard. 
 
-The configuration file is written in YAML, and is structured in a way that is easy to read and 
-write.
+The configuration is defined at the top of the file in YAML enclosed by two horizontal rules marked with dashes (---):
+
+``` yaml
+---
+order: -1
+height: 5
+---
+# Churn dashboard
+
+Welcome to our churn dashboard! Let me show you around ...
+```
 
 [[back to top](#dashboards-as-code)]
 
diff --git a/tests/unit/test_dashboards.py b/tests/unit/test_dashboards.py
index 10817660..54d617ec 100644
--- a/tests/unit/test_dashboards.py
+++ b/tests/unit/test_dashboards.py
@@ -177,9 +177,10 @@ def test_markdown_handler_parses_attribute_from_header(tmp_path, attribute):
     assert str(header[attribute]) == "10"
 
 
-def test_markdown_handler_splits_header(tmp_path):
+@pytest.mark.parametrize("horizontal_rule", ["---", "--------"])
+def test_markdown_handler_splits_header(tmp_path, horizontal_rule):
     path = tmp_path / "widget.md"
-    path.write_text("---\norder: 10\n---\n# Description")
+    path.write_text(f"{horizontal_rule}\norder: 10\n{horizontal_rule}\n# Description")
     handler = MarkdownHandler(path)
 
     header, content = handler.split()