From a0f337585df2209861b2738975f6953517f0181a Mon Sep 17 00:00:00 2001
From: Steven Noorbergen <91969936+steven-noorbergen@users.noreply.github.com>
Date: Fri, 3 Jan 2025 01:42:42 +0100
Subject: [PATCH] Add: some readme documentation on snippets (#97)

---
 README.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/README.md b/README.md
index e5e9dfc..6b9518e 100644
--- a/README.md
+++ b/README.md
@@ -122,3 +122,23 @@ It also means being open to feedback yourself, and being willing to learn from o
 
 It should be noted that this also means that sometimes pull requests will be rejected.
 A rejection does not mean that your contribution is not valued, but rather that it is not a good fit for the project at this point in time.
+
+# Conventions
+
+## Snippets
+
+There are various places where we insert code snippets into the documentation to better visualize what's going on.
+
+Snippets are placed in the `snippets` folder, grouped in subfolders by topic. Each snippet is a separate file per language (based off of its extension), with a central (autogenerated) `.md` file that includes the snippets for each language. If you want to add a new language to a snippet, create the new file, and the build pipeline will automatically include it in the final documentation.
+
+If you are adding the first snippet for a new language, it will need to be defined in `scripts/generate-snippets.py`, so that the build pipeline knows to include the file extension when searching for snippets, and what langauge to use for syntax highlighting.
+
+When adding new snippets, write it in any supported/configured language, and include it as follows:
+
+```markdown
+--8<-- "snippets/path/to-filename.md"
+```
+
+Note the .md extension to use the autogenerated file, and the `--8<--` to indicate that this is a snippet include.
+
+If a certain topic contains a lot of snippets, it might also be time to create a guide page for that topic, so that newer users can use that guide as a starting point.