diff --git a/.tools/readmes/render.py b/.tools/readmes/render.py
index 972cda0c1ed..f4e97cd335e 100644
--- a/.tools/readmes/render.py
+++ b/.tools/readmes/render.py
@@ -13,6 +13,7 @@
 from typing import Dict, List, Tuple
 
 import config
+from aws_doc_sdk_examples_tools.entities import expand_all_entities
 from aws_doc_sdk_examples_tools.metadata import Example
 from aws_doc_sdk_examples_tools.sdks import Sdk
 from aws_doc_sdk_examples_tools.services import Service
@@ -202,16 +203,6 @@ def _transform_custom_categories(self) -> Dict[str, List[Dict[str, str]]]:
                 sorted_cats[key] = post_cats[key]
         return sorted_cats
 
-    def _expand_entities(self, readme_text: str) -> str:
-        entities = set(re.findall(r"&[\dA-Za-z-_]+;", readme_text))
-        for entity in entities:
-            expanded = self.scanner.expand_entity(entity)
-            if expanded is not None:
-                readme_text = readme_text.replace(entity, expanded)
-            else:
-                logger.warning("Entity found with no expansion defined: %s", entity)
-        return readme_text
-
     def _lang_level_double_dots(self) -> str:
         return "../" * self.lang_config["service_folder"].count("/")
 
@@ -313,7 +304,10 @@ def render(self) -> RenderStatus:
             customs=customs,
             unsupported=unsupported,
         )
-        self.readme_text = self._expand_entities(self.readme_text)
+        [text, errors] = expand_all_entities(self.readme_text, self.scanner.doc_gen.entities)
+        if errors:
+            raise errors
+        self.readme_text = text
 
         # Check if the rendered text is different from the existing file
         if self.read_current() == self.readme_text:
diff --git a/.tools/readmes/scanner.py b/.tools/readmes/scanner.py
index 0582248428a..84001469378 100644
--- a/.tools/readmes/scanner.py
+++ b/.tools/readmes/scanner.py
@@ -29,8 +29,6 @@ def __init__(self, doc_gen: DocGen):
         self.sdk_ver: int = -1
         self.svc_name: str = ""
         self.snippets = None
-        self.entities: Dict[str, str] = {}
-        self._prepare_entities()
         self.examples: Dict[str, List[Example]] = {}
         self._build_examples()
         self.hellos: Dict[str, Example] = {}
@@ -41,15 +39,6 @@ def __init__(self, doc_gen: DocGen):
         self.crosses: Dict[str, Example] = {}
         self.cross_scenarios: Dict[str, Example] = {}
 
-    def _prepare_entities(self):
-        for svc in self.services().values():
-            if svc.expanded:
-                self.entities[svc.long] = svc.expanded.long
-                self.entities[svc.short] = svc.expanded.short
-        # config entities override
-        for entity, expanded in config.entities.items():
-            self.entities[entity] = expanded
-
     def load_crosses(self):
         self.doc_gen.process_metadata(
             self.doc_gen.root / ".doc_gen" / "metadata" / "cross_metadata.yaml"
@@ -112,9 +101,6 @@ def service(self) -> Service:
     def services(self) -> Dict[str, Service]:
         return self.doc_gen.services
 
-    def expand_entity(self, entity):
-        return self.entities[entity]
-
     def snippet(self, example: Example, readme_folder, api_name: str):
         if self.lang_name not in example.languages:
             return None