diff --git a/doc/PhpAnnotations.md b/doc/PhpAnnotations.md
index dcc1901..d656f83 100644
--- a/doc/PhpAnnotations.md
+++ b/doc/PhpAnnotations.md
@@ -1,3 +1,9 @@
+---
+title: PHP annotations
+---
+
+Here we document the PHP code annotations that are used and defined by different (static) analyses in this project.
+
 Syntax of `@param`
 
 ```
@@ -34,4 +40,4 @@ Syntax of `@var`
 @var mixed $in
 @var \ClassObject $classObj
 @var \Namespace\ClassObject $classObj
-```
\ No newline at end of file
+```
diff --git a/doc/PhpConstraintOperations.md b/doc/PhpConstraintOperations.md
index e69de29..4092af3 100644
--- a/doc/PhpConstraintOperations.md
+++ b/doc/PhpConstraintOperations.md
@@ -0,0 +1,5 @@
+---
+title: PHP Constraint Operations
+---
+
+(((TODO)))
diff --git a/doc/declarations.md b/doc/declarations.md
index 239ba72..22e8e22 100644
--- a/doc/declarations.md
+++ b/doc/declarations.md
@@ -1,3 +1,9 @@
+---
+title: Declarations
+---
+
+Here we document the qualified naming scheme for the locations  we used.
+
 * namespaces
     * `|php+namespace:///a/b|` for namespace `A\B`
     * `|php+namespace:///|` for global namespace
diff --git a/doc/number_of_duplicate_classes.md b/doc/number_of_duplicate_classes.md
index a3063bb..90fb76a 100644
--- a/doc/number_of_duplicate_classes.md
+++ b/doc/number_of_duplicate_classes.md
@@ -1,38 +1,41 @@
+---
+title: Example statistics
+---
+
+This is a very simple example report that PHP analysis can produce.
+
 # Some stats
 
----
 * Total number of class decls: 4021
 * Unique class paths: 4021 (100%)
 * Unique class names: 3997 (99%)
 
----
 * Total number of interfaces decls: 160
 * Unique interfaces paths: 160 (100%)
 * Unique interfaces names: 156 (97%)
 
----
 * Total number of trait decls: 0
 * Unique trait paths: 0 (0%)
 * Unique trait names: 0 (0%)
 
----
 * Total number of mixed decls: 4181
 * Unique mixed paths: 4181 (100%)
 * Unique mixed names: 4152 (99%)
 
-Type | Total | Unique Paths* | Unique Names* | Number of non unique:
-- | - | - | - | -
-class | 4021 | 4021 (100%) | 3997 (99%) | 24
-interface | 160 | 160 (100%) | 156 (97%) | 4
-trait | 0 | 0 (100%) | 0 (100%) | 0
-mixed | 4181 | 4181 (100%) | 4152 (99%) | 27
+| Type | Total | Unique Paths | Unique Names | Number of non unique |
+| - | - | - | - | - |
+| class | 4021 | 4021 (100%) | 3997 (99%) | 24 |
+| interface | 160 | 160 (100%) | 156 (97%) | 4 |
+| trait | 0 | 0 (100%) | 0 (100%) | 0 |
+| mixed | 4181 | 4181 (100%) | 4152 (99%) | 27 |
 
 \* `Unique Paths` contain the namespace, `Unique Names` only the name of the class.
 
 List of duplicate class names:
 
 
-
+```
 <a.x, 425234>
 <b.y, 425234>
 <c.x, 425234>
+```
diff --git a/doc/php_type_constraint_operations.md b/doc/php_type_constraint_operations.md
index 84507b3..685625c 100644
--- a/doc/php_type_constraint_operations.md
+++ b/doc/php_type_constraint_operations.md
@@ -1,9 +1,10 @@
-# Php Type Constraint Operations
+---
+title: PHP Type Constraint Operations
+---
 
-Some examples:
+Here we document some examples of the type inference constraints  we extract from PHP code.
 
-
-**Assign operators (some sort of case)**
+## Assign operators (some sort of case)
 
 ```
 $a .= ... // $a is a String
@@ -14,7 +15,7 @@ $x = (int) $y; // $x = Integer
 $x = 1; // $x = Integer
 ```
 
-**Method call**
+## Method call
 
 ```
 $a -> methodCall();
@@ -22,7 +23,7 @@ $a -> methodCall();
 
 ```
 
-** Conditional statements **
+## Conditional statements 
 
 ```
 $a instanceOf "C" // is_a
@@ -32,7 +33,7 @@ is_numeric($a) // $a is numeric
 is_bool($a) // $a is a boolean
 ```
 
-** Member addition **
+## Member addition 
 
 ```
 class Empty {}
@@ -41,13 +42,13 @@ $e->newField = "value"; // newField is added
 echo $e->newField; // newField is used
 ```
 
-** Return types of methods and functions **
+## Return types of methods and functions 
 
 ```
 function f () { return true }; // return type of f is a boolean
 ```
 
-** Object instantiation **
+## Object instantiation 
 
 ```
 $x = new Obj; // $x = instance of class Obj
@@ -63,7 +64,7 @@ getPersonId(new Person(), 1, 2, true); // correct
 getPersonId(); // incorrect
 ```
 
-** self/static/parent **
+## self/static/parent **
 
 ```
 self::methodCall(); // current class
@@ -71,7 +72,7 @@ parent::methodCall(); // one of the parent classes
 static::methodCall(); // class of instantiation
 ```
 
-** Out of scope **
+## Out of scope 
 
 ```
 - Variable variables (resolve to everything)
@@ -80,8 +81,8 @@ static::methodCall(); // class of instantiation
 ```
 
 
-** Other Notes **
+## Other Notes
 
 ```
 non parsing scripts are ignored
-```
\ No newline at end of file
+```
diff --git a/doc/possible_type_constraints.md b/doc/possible_type_constraints.md
index 3a95ba8..f5fc7e9 100644
--- a/doc/possible_type_constraints.md
+++ b/doc/possible_type_constraints.md
@@ -1,4 +1,8 @@
-##### Possible Type Constraints:
+---
+title: Possible Type Constraints
+---
+
+This is design inspiration for the type inference algorithm.
 
 Declarations:
 
@@ -10,7 +14,7 @@ There are differnt 'levels' of constraints.
 * On function/method level (what variables are used within the scope)
 * Between scopes (for method calls)
 
-** Types: **
+## Types: 
 
 * a variable `$a` has { t1, ..., tn } types. (within a certain scope)
 * assignement of variables: `$x = $y` (types of y = types of x)
@@ -25,7 +29,7 @@ There are differnt 'levels' of constraints.
 
 #### Declarations
 
-** Variable **
+## Variable 
  
  * The type of a variable is the type of the disjunction of all occurances of the variable within a within the scope.
  * On scopes:
@@ -34,20 +38,20 @@ There are differnt 'levels' of constraints.
    * method scope
    * exception for global key word, it is in the global scope AND in the function/method scope
 
-** Constants **
+## Constants 
  
  * Constant
 
-** Interface **
+## Interface 
 
  * Decl: name of the interface
  * Decl: extends (= subtype of ...)
 
-** Trait **
+## Trait 
 
 ?? out of scope ?? (not used alot, yet... can be added later)
 
-** Class **
+## Class 
 
  * Decl: name of the class (including namespace)
  * Decl: extends (= subtype of ...)
@@ -55,31 +59,31 @@ There are differnt 'levels' of constraints.
  * Decl: has constructor
  * Decl: constructor minimum re	quired fields
   
-** Class Constant **
+## Class Constant
 
  * Decl: name of the constant
  * Decl: class of the constant
  * Decl: type of the constant (?)
  
-** Class Property **
+## Class Property 
 
  * Decl: name of the property
  * Decl: class of the property
 
-** Class Methods (/function) **
+## Class Methods (/function) 
 
  * Decl: name of the method
  * Decl: has parameter constraints (see below)
  * Decl: which class the method is in 
  * The return type is the disjunction of the types of all return statements (or void/null when none provided)
  
-** Function **
+## Function
 
  * Decl: name of the function (including namespace)
  * Decl: has parameter constraints (see below)
  * The return type is the disjunction of the types of all return statements (or void/null when none provided)
 
-** Actual Parameter constraints **
+## Actual Parameter constraints 
  
  * Decl: Minimum required params
  * Decl: type hints
@@ -87,7 +91,7 @@ There are differnt 'levels' of constraints.
  
 #### Types
 
-** Cast operators **
+## Cast operators 
 
  Casts     | Input                            | Output      | Rascal                | Notes
 --- | --- | --- | --- | ---
@@ -110,7 +114,7 @@ There are differnt 'levels' of constraints.
 
 ---
 
-** Rules for Negation operator: ** `-l` -> (double | int)
+## Rules for Negation operator: `-l` -> (double | int)
 
 `l` | result
 --- | ---
@@ -120,7 +124,7 @@ _ | integer
 
 ---
 
-** Rules for Addition operator: ** `l + r` -> (array | double | int)
+## Rules for Addition operator: `l + r` -> (array | double | int)
 
 `l` | `r` | result
 --- | --- | ---
@@ -133,11 +137,11 @@ _ | _ | integer
 
 ---
 
-** Rules for Subtraction operator: ** `l - r` -> (double | int)
+## Rules for Subtraction operator:  `l - r` -> (double | int)
 
-** Rules for Multiplication operator: ** `l * r` -> ( double | int)
+## Rules for Multiplication operator:  `l * r` -> ( double | int)
 
-** Rules for Division operator: ** `l / r` -> (double | int)
+## Rules for Division operator:  `l / r` -> (double | int)
 
 `l` | `r` | result
 --- | --- | ---
@@ -149,7 +153,7 @@ _ | _ | integer
 
 ---
 
-** Rules for Modulus operator: ** `l % r` -> (int)
+## Rules for Modulus operator:  `l % r` -> (int)
 
 `l` | `r` | result
 --- | --- | ---
@@ -182,11 +186,11 @@ Code | typeOf(`$b`) | typeOf(`$a`) | Notes
 
 ### Bitwise Operators:
 
-** Rules for Bitwise And operator: ** `$a & $b`
+## Rules for Bitwise And operator:  `$a & $b`
 
-** Rules for Bitwise Or (inclusive or) operator: ** `$a | $b`
+## Rules for Bitwise Or (inclusive or) operator:  `$a | $b`
 
-** Rules for Bitwise Or (exclusive or) operator: ** `$a ^ $b`
+## Rules for Bitwise Or (exclusive or) operator:  `$a ^ $b`
 
 typeOf(`$a`) | typeOf(`$b`) | Result | Notes
 --- | --- | --- | ---
@@ -195,9 +199,9 @@ _ | _ | integer
 
 ---
 
-** Rules for Bitwise Shift left operator: ** `$a << $b`
+## Rules for Bitwise Shift left operator:  `$a << $b`
 
-** Rules for Bitwise Shift right operator: ** `$a >> $b`
+## Rules for Bitwise Shift right operator: `$a >> $b`
 
 
 typeOf(`$a`) | typeOf(`$b`) | Result | Notes
@@ -206,7 +210,7 @@ _ | _ | integer | always an integer
 
 ---
 
-** Rules for Bitwise Not operator: ** `~$a`
+## Rules for Bitwise Not operator: `~$a`
 
 typeOf(`$a`) | Result | Notes
 --- | --- | --- | ---
@@ -218,23 +222,23 @@ _ | error
 
 ### Comparison Operators:
 
-** Rules for Equal operator: ** `$a == $b`
+## Rules for Equal operator: `$a == $b`
 
-** Rules for Identical operator: ** `$a === $b`
+## Rules for Identical operator: `$a === $b`
 
-** Rules for Not equal operator: ** `$a != $b`
+## Rules for Not equal operator: `$a != $b`
 
-** Rules for Not equal operator: ** `$a <> $b`
+## Rules for Not equal operator: `$a <> $b`
 
-** Rules for Not identical operator: ** `$a !== $b`
+## Rules for Not identical operator: `$a !== $b`
 
-** Rules for Less then operator: ** `$a < $b`
+## Rules for Less then operator: `$a < $b`
 
-** Rules for Greater then operator: ** `$a > $b`
+## Rules for Greater then operator: `$a > $b`
 
-** Rules for Less or equal operator: ** `$a <= $b`
+## Rules for Less or equal operator: `$a <= $b`
 
-** Rules for Greater or equal operator: ** `$a >= $b`
+## Rules for Greater or equal operator: `$a >= $b`
 
 typeOf(`$a`) | typeOf(`$b`) | Result | Notes
 --- | --- | --- | ---
@@ -244,9 +248,9 @@ _ | _ | boolean | always a boolean
 
 ### Incrementing/Decrementing operators
 
-** Rules for Pre-increment operator: ** `++$a`
+## Rules for Pre-increment operator: `++$a`
 
-** Rules for Post-increment operator: ** `$a++`
+## Rules for Post-increment operator: `$a++`
 
 typeOf(`$a`) | Result | Notes
 --- | --- |---
@@ -255,9 +259,9 @@ null | integer
 _ | _ | other types do not change type
 
 ---
-** Rules for Pre-decrement operator: ** `--$a`
+## Rules for Pre-decrement operator: `--$a`
 
-** Rules for Post-decrement operator: ** `$a--`
+## Rules for Post-decrement operator: `$a--`
 
 typeOf(`$a`) | Result | Notes
 --- | --- | ---
@@ -268,17 +272,17 @@ _ | _ | other types do not change type
 
 ### Logical Operators:
 
-** Rules for And operator: ** `$a and $b`
+## Rules for And operator: `$a and $b`
 
-** Rules for Or operator: ** `$a or $b`
+## Rules for Or operator: `$a or $b`
 
-** Rules for Xor equal operator: ** `$a xor $b`
+## Rules for Xor equal operator: `$a xor $b`
 
-** Rules for Not equal operator: ** `!$a`
+## Rules for Not equal operator: `!$a`
 
-** Rules for And identical operator: ** `$a && $b`
+## Rules for And identical operator: `$a && $b`
 
-** Rules for Or then operator: ** `$a || $b`
+## Rules for Or then operator: `$a || $b`
 
 typeOf(`$a`) | typeOf(`$b`) | Result | Notes
 --- | --- | --- | ---
@@ -286,7 +290,7 @@ _ | _ | boolean | always a boolean
 
 ---
 
-** assignments **
+## assignments 
 
 ```
 $b = $a // (sub)typeOf($b) is (sub)typeOf($a)
@@ -294,7 +298,7 @@ $c = $b = $a; // (sub)typeOf($a) = (sub)typeOf($b) && (sub)typeOf($b) = (sub)typ
 
 ```
 
-** class instantiation **
+## class instantiation 
 
 ```
 $a = new A; // type of $a is class with name "A"; (FQN: Full Qualified Name)
@@ -303,7 +307,7 @@ $a = new A(1);	// type of $a is class with name "A"; (FQN: Full Qualified Name)
 				// minimum required params = 0 OR 1;
 ```
 
-** Ternary operator (elvis) **
+## Ternary operator (elvis) 
 
 ```
 $a ? $b : $c // result of this whole expression is: typeOf($b) OR typeOf($c)
@@ -311,11 +315,11 @@ $a ? $b : $c // result of this whole expression is: typeOf($b) OR typeOf($c)
 
 #### Other thoughts...
 
-** Assumption **
+## Assumption 
 
 I assume that the program is correct. But because it is hard to check if programs are fine in dynamic languagues this is a thread to validity.
  
-** Other **
+## Other 
 
 ?? Adding scope constraints??
 
@@ -339,7 +343,7 @@ Subtypes:
 		> class A extends B {}	
 
 ```
-** Note: ** add default classes, functions, variables and constants to the list of declarations
+## Note: add default classes, functions, variables and constants to the list of declarations
 
 
 Symbols:
@@ -362,7 +366,7 @@ $a->call($b)	| typeOf(a) has method "call" OR magic method __call
 
 ```
 
-** Constraint Examples **
+## Constraint Examples 
 
 ```
 syntax below: