feat: update readme

README.md

@@ -1,39 +1,81 @@
 # Flask-Template-Refs
 A Flask extension allowing easy access to templates with dot notation and auto-completion.
+
 ## Overview
 Keeping track of templates names when working on large Flask applications can be difficult, especially when working with libraries such as HTMX, which rely on rendering lots of template partials, often reused and shared across the whole application.
 
-This can become especially problematic when refactoring, forcing us to track down every render_template() call to make sure the proper template name is used.
+This can become problematic when refactoring, forcing us to track down render_template() calls to make sure the proper template name is passed to the renderer.
 
 This extension aims to solve these issues and improve developer experience when working with templates.
 ## Features
 
 ### Access templates easily with dot notation
-Templates are referenced with simple names in a dedicated class as instance attributes, so that you can use dot notation rather than strings and square brackets.
+Templates are referenced by short snake_case names in as instance attributes of a dedicated class, so that you can use dot notation rather than strings and square brackets.
 
 #### Before:
+
 ```python
 from jinja_partials import render_partial
 
 render_partial("shared/forms/inputs/file_input.jinja")
 ```
+
 #### After:
+
 ```python
 from flask_template_refs import refs
 from jinja_partials import render_partial
 
 render_partial(refs.file_input)
 ```
-### Organize your template files however you like
+
+### Keep track of every template, no matter where they are located
+
 Wether you create create sub directories or set blueprint specific folders, all templates listed in your app and its blueprints are mapped to a single object.
 
-In case of templates sharing the same name, the name of their parent directory is appended at the start of its reference name.
+Templates belonging to a specific blueprint include its name in the reference, provided the blueprint's template folder is not nested inside the app template folder.
+
+In case of templates sharing the same name the name of their direct parent is appended to the reference name of the deepest one.
+
+*Important:* It is not currently possible to differentiate between templates that share the same name when they are located at the root of their template folder.
+
+The first template found **always** take precedence when loading templates in Flask: the blueprint specific templates are found, but discarded in favor of the other.
+
+This is default behavior and can only be prevented by using unique names or nesting one of them one level deeper.
+
 
 #### Example:
 
-`"button.jinja"`  and `"/templates/login/button.jinja"` are referenced under `refs.button` and `refs.login_button`.
+Consider this project structure:
+
+```
+my-project/
+├── my_app/
+├──── \_\_init\_\_.py
+├──── templates/
+├────── button.jinja
+├────── forms/
+├──────── button.jinja
+├──── blueprints/
+├────── login/
+├──────── login.py
+├──────── templates/
+└────────── button.jinja
+
+```
+
+The extension manages to create distinct references for every template, but it is impossible to render the `button` located under `login/`:
+
+*The first `button.jinja` located under `my_project/templates/` is `button`.
+
+*The second one, nested one level below under `forms/` is `form_button`.
+
+*The third one under `login` is referenced as `login_button`, but can never be loaded by Flask as the first one takes precedence.
+
+
+
+### Enjoy auto-completion and linting
 
-### Benefit from auto-completion and linting
 If a template's reference changes, you'll be able to catch it immediatly with the linter of your choice. You'll also benefit from suggestions and auto-completion, sparing you from having to remember every template's actual name.
 
 ![Auto-completion in Neovim](/assets/autocompletion-example.png)
@@ -70,6 +112,7 @@ def create_app(test_config=None):
 ```
 
 ### Import the `refs` module wherever you need to access templates
+
 ```python
 from flask_template_refs import refs