feat: update readme

README.md

@@ -8,6 +8,36 @@ Bidirectional mapping between Markdown and JSON (Schema.org-style) via small, de
 *   **Declarative Templates:** Define your mappings with concise, easy-to-understand templates.
 *   **JSON Schema Validation:** Validate parsed JSON against Schema.org entities using JSON Schema.
 
+## How it works
+
+Marka uses a custom template file to enable bidirectional between Markdown and Data. A minimal `marka` schema could look like:
+
+```markdown
+# { articleTitle }
+
+{ articleBody }
+```
+
+Then it could parse the following markdown:
+
+```markdown
+# MyArticle
+
+The article body which could 
+contain newlines.
+```
+
+Into the following data:
+
+```json
+{
+  "articleTitle": "MyArticle",
+  "articleBody": "The article body which could\ncontain newlines.",
+}
+```
+
+And reversely if you give it the json it could reproduce the input markdown. If you want to dive into the deeper workings of the template look at [template/README.md](./template/README.md)
+
 ## Docker Image (CRUD API)
 
 A Docker image is available to transform a specified directory into a CRUD API. This allows you to expose your Markdown-to-JSON mappings as a web service.