diff --git a/README.md b/README.md
index 9b722be..63bef7d 100644
--- a/README.md
+++ b/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.
diff --git a/template/README.md b/template/README.md
new file mode 100644
index 0000000..254c51a
--- /dev/null
+++ b/template/README.md
@@ -0,0 +1,118 @@
+# Marka Template Language
+
+The marka template languages uses curly braces (`{`/`}`) to seperate `data` content from `matching` content.
+
+The data content is extracted from the markdown file during parsing and replaced by actual data during rendering.
+
+The `data` parts aka `data-blocks` support two different syntaxes which with they are defined. 
+
+## Short Syntax
+
+The first is the "short" syntax which may look like one of the following:
+
+```
+{ articleTitle }
+{ articleId | number }
+{ articleTags | hashtags,optional }
+```
+
+Before the `|` character is the path of the data block inside the data. After the (optional) `|` come comma seperated flags on how to parse/render this specific block.
+
+## Long Syntax
+
+The long syntax uses `yaml` to define the `data-blocks`:
+
+```
+{
+  path: recipeIngredient
+  codec: list
+  listTemplate: "- { . }"
+}
+```
+
+## Codecs
+
+Codecs are the predefined ways on how to parse/render `data-blocks`. The current list of codecs looks like this:
+
+- text
+- number
+- yaml
+- list
+- const
+- hashtags
+
+While `text` or `number` may be self explanatory the other codecs may require some more explanation.
+
+### Const Codec
+
+The const codec is used to specify fields which should always be the same during rendering. For example if for a specified template the title should always be the same when rendering/parsing:
+
+```
+# {
+  path: articleTitle
+  codec: const
+  value: TestArticle
+}
+```
+
+> Note: You need to supply a "value" with the "const" codec otherwise the application will throw an error
+
+
+### List Codec
+
+The list codec is used to parse/render list blocks like the following:
+
+```markdown
+# Ingredients
+- Flour
+- Water
+- Yeast
+- Salt
+```
+
+Or even numbered lists like:
+
+```markdown
+# Steps
+1. Mix all the ingredients except salt
+2. Let the dough sit for 1/2 hour (autolyse)
+3. Add the salt
+4. Knead again
+```
+
+To parse the steps list you could use a template like this:
+
+```markdown
+# Steps
+{
+  path: recipeInstructions
+  codec: list
+  listTemplate: "{ @index }. { . }"
+}
+```
+
+The `listTemplate` is a required field on the `list` block. It uses the same syntax as the template itself, with the special edition of a `@index` variable to handle the index in numbered lists.
+
+### Yaml  Codec
+
+The `yaml` codec parses parses/renders its content as yaml. Every field inside the yaml needs to be specified:
+
+```
+{
+  path: .
+  codec: yaml
+  fields:
+    - path: "@context"
+      codec: const
+      value: https://schema.org
+      hidden: true
+    - path: "@schema"
+      codec: const
+      value: Article
+      hidden: true
+    - path: "@type"
+      codec: const
+      value: Article
+}
+```
+