feat: update readme

2025-10-01 16:45:18 +02:00
parent 69c2550f44
commit 8140ea856c
2 changed files with 148 additions and 0 deletions
--- a/template/README.md
+++ 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
+}
+```
+