diff --git a/readme.md b/readme.md
index 2b504e3..af8f54f 100644
--- a/readme.md
+++ b/readme.md
@@ -1,16 +1,71 @@
 # ManiaTemplates
 
-A templating engine to use for ManiaLinks, an XML based markup language for the game Trackmania.
+A XML based template engine to use for creating UI elements in the game Trackmania.
+Components are used to build complex UIs with the limited set of UI elements the game provides.
+This template engine eases the creation of UIs by providing loops, conditional access and properties that data can be
+passed to.
 
-## Setup Rider to support mt-files
-
-* Go to **Editor > File Types**, select *XML* in the recognized file types list.
-* Add *.mt* on the right side.
+Used in [EvoSC#](https://github.com/EvoEsports/EvoSC-sharp), our new server controller.
+We're using ``.mt`` file extension to discriminate ManiaTemplate from other XML files,
+using `.xml` would work just as well.
 
 ## Components
+
+Components are reusable UI elements with optional properties and at least a template that defines the markup.
+Any component can be included in another one, or rendered individually.
+
+### Example component
+
+The XML below shows an example component importing namespaces and other components, as well as defining two properties,
+a template with conditional rendering and loops.
+
+````xml
+
+<component>
+    <!-- import namespaces -->
+    <using namespace="System.Linq"/>
+
+    <!-- import other components -->
+    <import component="DescriptionBox" as="DescriptionBox"/>
+    <import component="Window" as="Wrapper"/>
+
+    <!-- define properties -->
+    <property name="title" type="string"/>
+    <property name="description" type="string" default="No descripption available."/>
+
+    <!-- create the markup -->
+    <template>
+        <Wrapper foreach="int i in Enumerable.Range(1, 3)">
+            <label if="i > 1" text="{{ title + i }}"/>
+            <DescriptionBox description="{{ description }}"/>
+        </Wrapper>
+    </template>
+</component>
+````
+
+### How it works
+
+Before rendering a template, all components are combined into a
+single [T4 file](https://learn.microsoft.com/en-us/visualstudio/modeling/code-generation-and-t4-text-templates), which
+then is pre-compiled into a C# class.
+Pre-compiling to C# class allows very fast rendering (1-3ms).
+
+````mermaid
+flowchart LR
+    components(component1.mt
+    component2.mt
+component3.mt) -->|combine & convert|t4(template.t4)
+t4 -->|pre compile|cs(template.cs)
+cs -->|render|out["`*XML string*`"]
+````
+
+### List of included components
+
 [List of global components](components.md)
 
-## Example
+## Code example
+
+How to add component files and render a template.
 
 ````csharp
 //Prepare template engine
@@ -27,15 +82,25 @@ mapList.PreProcess();
 var result = mapList.RenderAsync(GetMapListData());
 ````
 
+## Setup Rider to recognize mt-files
+
+* Go to **Editor > File Types**, select *XML* in the recognized file types list.
+* Add *.mt* on the right side.
+
 ## How to add embedded resources
+
 You can use different sources, but in general we'll use embedded resources for our templates.
+
 ### In Rider
+
 Right-click a file, go to **Properties**, then under **Build Action** select *Embedded Resource*.
 
 To add a whole directory, add the following to the *.csproj* file:
+
 ````xml
+
 <ItemGroup>
-  <None Remove="Templates\**\*" />
-  <EmbeddedResource Include="Templates\**\*" />
+    <None Remove="Templates\**\*"/>
+    <EmbeddedResource Include="Templates\**\*"/>
 </ItemGroup>
 ````
\ No newline at end of file