diff --git a/README.md b/README.md
index 94685df..dcfa123 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,8 @@
 
 # pyChangeLogHelper
 
-A simple changelog formater that consume merged commit message and produce nice pre-formated changelogs
+A simple changelog formater that consume raw changes list text and produce nice pre-formated changelogs.
+The input data mainly aim to be a merged commit report.
 
 Checkout [Latest Documentation](https://chacha.ddns.net/mkdocs-web/chacha/pychangelogfactory/master/latest/).
 
diff --git a/docs-static/usage.md b/docs-static/usage.md
index e07877b..80ad12a 100644
--- a/docs-static/usage.md
+++ b/docs-static/usage.md
@@ -3,20 +3,26 @@
 ## Theory
 
 This lib will try to extract normalized changes from a given raw history.
+
 _It's up to the user to provide this merged history._
 
 To realize this job, parsing is done in two rounds:
+
 - first round extrats formal changes messages: e.g.: <change_type>(<change_target>): <change_message>
 - secound round extracts lines from remaining ones based on keywords dictionnaries
 
-Note:
-    For formal (1) search, lines must contain at least 2 words
-    For keywords (2) search, lines must contain at least 3 words
+/// note | searching policy
+    type: warning
+When formal search (1), _lines must contain at least 2 words_
+When keywords search (2), _lines must contain at least 3 words_
+///
 
-Note:
-    lines with comment tags are ignored:
-    - `[space]*//`
-    - `[space]*#`
+/// note | ignored lines
+lines with comment tags are ignored:
+
+- `[space]*//`
+- `[space]*#`
+///
 
 ## Installation
 
diff --git a/mkdocs.yml b/mkdocs.yml
index f8fa45d..f2facd0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -67,6 +67,9 @@ markdown_extensions:
   - tables
   - attr_list
   - abbr
+  - pymdownx.blocks.admonition
+  - pymdownx.blocks.definition
+  - pymdownx.blocks.details
   - pymdownx.betterem:
       smart_enable: all
   - pymdownx.caret