diff --git a/docs/intro/instances.rst b/docs/intro/instances.rst
index e68fb612e0e..f820a9cec0b 100644
--- a/docs/intro/instances.rst
+++ b/docs/intro/instances.rst
@@ -4,6 +4,11 @@
 Instances
 =========
 
+test |gelcmd|
+
+test2 :gelcmd:`migrate --help`
+
+
 Let's get to the good stuff. You can spin up an Gel instance with a single
 command.
 
diff --git a/edb/tools/docs/edb.py b/edb/tools/docs/edb.py
index 137ae22091b..f691ed190c8 100644
--- a/edb/tools/docs/edb.py
+++ b/edb/tools/docs/edb.py
@@ -150,15 +150,38 @@ def apply(self):
             nt = node.astext()
             if nt in {"Gel", "EdgeDB", "gelcmd", ".gel", "gel.toml"}:
                 if builder_name in {"xml", "edge-xml"}:
-                    sub = d_nodes.inline(
-                        nt, nt, **{"edb-substitution": "true"}
-                    )
+                    if nt == "gelcmd":
+                        sub = d_nodes.literal(
+                            'gel', 'gel',
+                            **{
+                                "edb-gelcmd": "true",
+                                "edb-gelcmd-top": "true",
+                                "edb-substitution": "true",
+                            }
+                        )
+                    else:
+                        sub = d_nodes.inline(
+                            nt, nt, **{"edb-substitution": "true"}
+                        )
                     node.replace_self(sub)
                 else:
                     node.replace_self(d_nodes.Text(nt))
 
+class GelCmdRole:
+
+    def __call__(
+        self, role, rawtext, text, lineno, inliner, options=None, content=None
+    ):
+        text = f'gel {text.strip()}'
+        node = d_nodes.literal(text, text)
+        node["edb-gelcmd"] = "true"
+        node["edb-gelcmd-top"] = "false"
+        node["edb-substitution"] = "true"
+        return [node], []
+
 
 def setup_domain(app):
+    app.add_role('gelcmd', GelCmdRole())
     app.add_domain(GelDomain)
     app.add_transform(GelSubstitutionTransform)
 
diff --git a/tests/test_docs_sphinx_ext.py b/tests/test_docs_sphinx_ext.py
index 24099f827c3..13e1d015284 100644
--- a/tests/test_docs_sphinx_ext.py
+++ b/tests/test_docs_sphinx_ext.py
@@ -956,7 +956,6 @@ def test_sphinx_edb_brand_name_01(self):
         '''
 
         out = self.build(src, format='xml')
-        print(out, '\n')
         x = requests_xml.XML(xml=out)
 
         self.assertEqual(
@@ -967,3 +966,36 @@ def test_sphinx_edb_brand_name_01(self):
 
 
         print(x)
+
+    def test_sphinx_edb_brand_name_02(self):
+        src = '''
+        blah |gelcmd|
+        blah 2 :gelcmd:`migrate --help`
+
+
+        DONE
+        '''
+
+        out = self.build(src, format='xml')
+        x = requests_xml.XML(xml=out)
+
+        self.assertEqual(
+            x.xpath('''
+                //paragraph/literal
+                    [@edb-substitution="true"]
+                    [@edb-gelcmd="true"]
+                    [@edb-gelcmd-top="true"]
+                    / text()
+            '''),
+            ['gel'])
+
+        self.assertEqual(
+            x.xpath('''
+                //paragraph/literal
+                    [@edb-substitution="true"]
+                    [@edb-gelcmd="true"]
+                    [@edb-gelcmd-top="false"]
+                    / text()
+            '''),
+            ['gel migrate --help'])
+