diff --git a/examples/numpy.toml b/examples/numpy.toml
index 4c7a6f8b..5c4a50f1 100644
--- a/examples/numpy.toml
+++ b/examples/numpy.toml
@@ -90,3 +90,6 @@ docspage = 'https://numpy.org/doc/1.26/'
 [global.expected_errors]
 VisitCitationReferenceNotImplementedError = ["numpy.fft"]
 
+[global.substitution_definitions]
+version = '1.2.3'
+
diff --git a/papyri/crosslink.py b/papyri/crosslink.py
index 191575e9..ca72a875 100644
--- a/papyri/crosslink.py
+++ b/papyri/crosslink.py
@@ -313,8 +313,8 @@ def _ingest_examples(
                 f"TBD (examples, {path}), supposed to be QA",
                 known_refs,
                 set(),
-                {},
-                aliases,
+                substitution_defs={},
+                aliases=aliases,
                 version=version,
                 config={},
             )
diff --git a/papyri/gen.py b/papyri/gen.py
index 77522a45..fc9caeb2 100644
--- a/papyri/gen.py
+++ b/papyri/gen.py
@@ -99,6 +99,8 @@
 # delayed import
 if True:
     from .myst_ast import MText
+    from .myst_ast import ReplaceNode
+    from .myst_ast import MParagraph
 
 
 class ErrorCollector:
@@ -433,6 +435,7 @@ class Config:
     fail_unseen_error: bool = False
     execute_doctests: bool = True
     directives: Dict[str, str] = dataclasses.field(default_factory=lambda: {})
+    substitution_definitions: Dict[str, str] = dataclasses.field(default_factory=dict)
 
     def replace(self, **kwargs):
         return dataclasses.replace(self, **kwargs)
@@ -1456,6 +1459,18 @@ def collect_narrative_docs(self):
         trees = {}
         title_map = {}
         blbs = {}
+        global_substitutions = {}
+        for k, v in self.config.substitution_definitions.items():
+            res = ts.parse(v.encode(), qa="global_substitution")
+            # HERE are some assumptions as we are parsing a "full document" with tree sitter
+            # this is going to give a single Section with a single paragraph.
+            sec: Section
+            [sec] = res
+            assert isinstance(sec, Section)
+            [par] = sec.children
+            assert isinstance(par, MParagraph)
+            par: MParagraph
+            global_substitutions["|" + k + "|"] = [ReplaceNode(k, v, par.children)]
         with self.progress() as p2:
             task = p2.add_task("Parsing narrative", total=len(files))
 
@@ -1477,11 +1492,16 @@ def collect_narrative_docs(self):
                 blob = DocBlob.new()
                 key = ":".join(parts)[:-4]
                 try:
+                    from copy import copy
+
+                    G = copy(global_substitutions)
+                    G.update({})
+                    ref_set: frozenset[RefInfo] = frozenset({})
                     dv = DVR(
                         key,
-                        set(),
+                        ref_set,
                         local_refs=set(),
-                        substitution_defs={},
+                        substitution_defs=G,
                         aliases={},
                         version=self._meta["version"],
                         config=self.config.directives,
diff --git a/papyri/take2.py b/papyri/take2.py
index a7840144..6d35c051 100644
--- a/papyri/take2.py
+++ b/papyri/take2.py
@@ -207,6 +207,8 @@ class SubstitutionRef(UnserializableNode):
     value: str
 
     def __init__(self, value):
+        assert value.startswith("|")
+        assert value.endswith("|")
         self.value = value
 
     def to_json(self):
diff --git a/papyri/tree.py b/papyri/tree.py
index 93bbd16f..d152c000 100644
--- a/papyri/tree.py
+++ b/papyri/tree.py
@@ -8,7 +8,7 @@
 
 from collections import Counter, defaultdict
 from functools import lru_cache
-from typing import Any, Dict, FrozenSet, List, Set, Tuple, Callable
+from typing import Any, Dict, FrozenSet, List, Set, Tuple, Callable, Union
 
 from .take2 import (
     Directive,
@@ -533,12 +533,15 @@ class DirectiveVisiter(TreeReplacer):
 
     """
 
+    substitution_defs: Dict[str, Union[ReplaceNode, MImage]]
+
     def __init__(
         self,
         qa: str,
         known_refs: FrozenSet[RefInfo],
         local_refs,
         substitution_defs,
+        *,
         aliases,
         version,
         config=None,