Start adding a Markdown writing guide for our docs

Signed-off-by: Julius Volz <julius.volz@gmail.com>

README.md

@@ -16,6 +16,8 @@ The documentation hosted on this website is pulled together from multiple reposi
 
 As a guideline, please keep the documentation generally applicable and avoid use-case-specific changes.
 
+For guidelines around Markdown formatting and available frontmatter fields and features, please see the [Markdown guide](markdown-guide.md).
+
 ## Building and running the website
 
 ### Prerequisites

markdown-guide.md

@@ -0,0 +1,35 @@
+# Guide around Markdown features, formatting, and frontmatter fields
+
+This document gives an overview of the Markdown features and formatting options available for the docs in this repository. It also provides information about the frontmatter fields that can be used to customize the behavior and appearance of the documentation pages.
+
+## Markdown features
+
+Generally, we use [GitHub Flavored Markdown](https://github.github.com/gfm/) for formatting.
+
+TODO: document admonitions
+TODO: document how to link between pages
+
+## Heading levels
+
+For both blog posts and documentation pages, adhere to the following heading rules:
+
+* DO NOT use any top-level headings (`# Heading`, `<h1>`) in the Markdown content itself. The final rendered page will include an automatic H1 heading based on the `title` frontmatter field.
+* Use second-level headings (`## Heading`, `<h2>`) for the main sections of a page and use lower-level headings for subsections as appropriate.
+
+## Frontmatter fields
+
+The following frontmatter fields are available:
+
+### For local and remote documentation pages
+
+* `title`: The title of the page. This is displayed as the main heading on the page and as the HTML page title.
+* `sort_rank`: The sort order of the page relative to sibling pages in the same directory. Pages with a lower sort rank will appear first in the navigation menu. Should start at 1 and be incremented by 1 for each page.
+* `nav_title` (OPTIONAL): The title to show in the navigation menu. If not set, the `title` field is used.
+* `hide_in_nav` (OPTIONAL): If set to `true`, the page will not be included in the navigation menu but still be accessible via its URL. TODO RENAME
+* `nav_icon` (OPTIONAL): The [Tabler](https://tabler.io/icons) icon to be displayed in the navigation menu for this section. This is only used for the top-level section index.md Markdown files. Any new icons need to be added to the `iconMap` in [`src/app/docs/layout.tsx`](src/app/docs/layout.tsx).
+
+### For blog posts
+
+* `title`: The title of the blog post. This is displayed as the main heading on the page and as the HTML page title.
+* `author_name`: The name of the author of the blog post.
+* `created_at`: The date of the blog post in `YYYY-mm-dd` format.