diff --git a/docs/README.md b/docs/README.md
index 0f91968b0b..d21723a3b7 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,6 +2,19 @@
 
 ## Markdown syntax available
 
+The default markdown syntax is supported when writing documentation.
+
+### Front matter
+
+Front matter is used to add metadata to your Markdown file (`title` & `description`). It is provided at the very top of the file, enclosed by three dashes `---`. The content is parsed as YAML.
+
+If not Front matter is detected, the metadata will be populated with the following:
+
+- `title`: first main title detected
+- `description`: first paragraph detected
+
+### Custom markdown syntax
+
 The documentation website [nx.dev](https://nx.dev) is using custom Markdown syntax to enable the authors to add functionality to its content.
 
 #### Callouts