diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md
index dcb35f5e..027ebaed 100644
--- a/docs/usage/configuration/docstrings.md
+++ b/docs/usage/configuration/docstrings.md
@@ -208,8 +208,8 @@ In that case, the Spacy tables can help.
 
 **Type**   | **Name**    | **Description**          | **Default**
 ---------- | ----------- | ------------------------ | -----------
-<code><span data-autorefs-optional="list">list</span>[<span data-autorefs-optional="int">int</span> \| <span data-autorefs-optional="float">float</span>]</code> | `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | *required*
-<code><span data-autorefs-optional="VacuumType">VacuumType</span> \| <span data-autorefs-optional="typing.Literal">Literal</span>["regular"]</code> | `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | `VacuumType.PLASMA`
+<code><autoref identifier="list" optional>list</autoref>[<autoref identifier="int" optional>int</autoref> \| <autoref identifier="float" optional>float</autoref>]</code> | `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | *required*
+<code><autoref identifier="VacuumType" optional>VacuumType</autoref> \| <autoref identifier="typing.Literal" optional>Literal</autoref>["regular"]</code> | `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | `VacuumType.PLASMA`
 ////
 
 //// tab | List
@@ -222,8 +222,8 @@ Lists work well whatever the length of names, type annotations, descriptions, et
 
 **Other Parameters:**
 
-- `gravity_forces` (<code><span data-autorefs-optional="list">list</span>[<span data-autorefs-optional="int">int</span> \| <span data-autorefs-optional="float">float</span>]</code>) &mdash; Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-- `vacuum_type` (<code><span data-autorefs-optional="VacuumType">VacuumType</span> \| <span data-autorefs-optional="typing.Literal">Literal</span>["regular"]</code>) &mdash; Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+- `gravity_forces` (<code><autoref identifier="list" optional>list</autoref>[<autoref identifier="int" optional>int</autoref> \| <autoref identifier="float" optional>float</autoref>]</code>) &mdash; Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+- `vacuum_type` (<code><autoref identifier="VacuumType" optional>VacuumType</autoref> \| <autoref identifier="typing.Literal" optional>Literal</autoref>["regular"]</code>) &mdash; Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 ////
 
 //// tab | Spacy
@@ -241,8 +241,8 @@ by reserving more horizontal space on the second column.
 
 **Name**    | **Description**
 ----------- | ---------------
-`gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<br>**TYPE:** <code><span data-autorefs-optional="list">list</span>[<span data-autorefs-optional="int">int</span> \| <span data-autorefs-optional="float">float</span>]</code> <span style="float: right;"><b>DEFAULT:</b> <i>required</i></span>
-`vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<br>**TYPE:**<code><span data-autorefs-optional="VacuumType">VacuumType</span> \| <span data-autorefs-optional="typing.Literal">Literal</span>["regular"]</code> <span style="float: right;"><b>DEFAULT:</b> <code>VacuumType.PLASMA</code></span>
+`gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<br>**TYPE:** <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="int" optional>int</autoref> \| <autoref identifier="float" optional>float</autoref>]</code> <span style="float: right;"><b>DEFAULT:</b> <i>required</i></span>
+`vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<br>**TYPE:**<code><autoref identifier="VacuumType" optional>VacuumType</autoref> \| <autoref identifier="typing.Literal" optional>Literal</autoref>["regular"]</code> <span style="float: right;"><b>DEFAULT:</b> <code>VacuumType.PLASMA</code></span>
 ////
 ///
 
diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md
index e4ddaec1..d8d7f250 100644
--- a/docs/usage/configuration/general.md
+++ b/docs/usage/configuration/general.md
@@ -139,7 +139,7 @@ def some_function():
 
 ## `preload_modules`
 
-- **:octicons-package-24: Type <code><span data-autorefs-optional="list">list</span>[<span data-autorefs-optional="str">str</span>] | None</code>  :material-equal: `None`{ title="default value" }**
+- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] | None</code>  :material-equal: `None`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
 Pre-load modules that are not specified directly in [autodoc instructions][autodoc syntax] (`::: identifier`).
diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md
index 1e5ff771..119d8294 100644
--- a/docs/usage/configuration/members.md
+++ b/docs/usage/configuration/members.md
@@ -2,8 +2,8 @@
 
 ## `members`
 
-- **:octicons-package-24: Type <code><span data-autorefs-optional="list">list</span>[<span data-autorefs-optional="str">str</span>] |
-    <span data-autorefs-optional="bool">bool</span> | None</code>  :material-equal: `None`{ title="default value" }**
+- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] |
+    <autoref identifier="bool" optional>bool</autoref> | None</code>  :material-equal: `None`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
 An explicit list of members to render.
@@ -97,8 +97,8 @@ INFO: **The default behavior (with unspecified `members` or `members: null`) is
 
 ## `inherited_members`
 
-- **:octicons-package-24: Type <code><span data-autorefs-optional="list">list</span>[<span data-autorefs-optional="str">str</span>] |
-    <span data-autorefs-optional="bool">bool</span></code>  :material-equal: `False`{ title="default value" }**
+- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] |
+    <autoref identifier="bool" optional>bool</autoref></code>  :material-equal: `False`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
 An explicit list of inherited members (for classes) to render.
@@ -331,7 +331,7 @@ def function_c():
 
 ## `filters`
 
-- **:octicons-package-24: Type <code><span data-autorefs-optional="list">list</span>[<span data-autorefs-optional="str">str</span>] | None</code>  :material-equal: `["!^_[^_]"]`{ title="default value" }**
+- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] | None</code>  :material-equal: `["!^_[^_]"]`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
 A list of filters applied to filter objects based on their name.
@@ -555,7 +555,7 @@ package
 [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
 [:octicons-tag-24: Insiders 1.2.0](../../insiders/changelog.md#1.2.0)
 
-- **:octicons-package-24: Type <code><span data-autorefs-optional="bool">bool</span> | <span data-autorefs-optional="dict">dict</span>[<span data-autorefs-optional="str">str</span>, <span data-autorefs-optional="bool">bool</span>]</code>  :material-equal: `False`{ title="default value" }**
+- **:octicons-package-24: Type <code><autoref identifier="bool" optional>bool</autoref> | <autoref identifier="dict" optional>dict</autoref>[<autoref identifier="str" optional>str</autoref>, <autoref identifier="bool" optional>bool</autoref>]</code>  :material-equal: `False`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
 Whether to render summaries of modules, classes, functions (methods) and attributes.
diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py
index b7fe3ad6..d5a88699 100644
--- a/src/mkdocstrings_handlers/python/rendering.py
+++ b/src/mkdocstrings_handlers/python/rendering.py
@@ -295,7 +295,10 @@ def do_crossref(path: str, *, brief: bool = True) -> Markup:
     full_path = path
     if brief:
         path = full_path.split(".")[-1]
-    return Markup("<span data-autorefs-optional-hover={full_path}>{path}</span>").format(full_path=full_path, path=path)
+    return Markup("<autoref identifier={full_path} optional hover>{path}</autoref>").format(
+        full_path=full_path,
+        path=path,
+    )
 
 
 @lru_cache
@@ -327,7 +330,7 @@ def repl(match: Match) -> str:
         path = match.group()
         path_var = f"path{group_number}"
         variables[path_var] = path
-        return f"<span data-autorefs-optional-hover={{{path_var}}}>{{{path_var}}}</span>"
+        return f"<autoref identifier={{{path_var}}} optional hover>{{{path_var}}}</autoref>"
 
     text = re.sub(r"([\w.]+)", repl, text)
     if code:
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja
index 396e36dd..34aa0119 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja
@@ -33,7 +33,7 @@ Context:
       <tbody>
         {% for attribute in section.value %}
           <tr class="doc-section-item">
-            <td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ attribute.name }}">{{ attribute.name }}</span></code></td>
+            <td><code><autoref identifier="{{ obj.path }}.{{ attribute.name }}" optional hover>{{ attribute.name }}</autoref></code></td>
             <td>
               {% if attribute.annotation %}
                 {% with expression = attribute.annotation %}
@@ -58,7 +58,7 @@ Context:
     <ul>
       {% for attribute in section.value %}
         <li class="doc-section-item field-body">
-          <b><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ attribute.name }}">{{ attribute.name }}</span></code></b>
+          <b><code><autoref identifier="{{ obj.path }}.{{ attribute.name }}" optional hover>{{ attribute.name }}</autoref></code></b>
           {% if attribute.annotation %}
             {% with expression = attribute.annotation %}
               (<code>{% include "expression"|get_template with context %}</code>)
@@ -85,7 +85,7 @@ Context:
       <tbody>
         {% for attribute in section.value %}
           <tr class="doc-section-item">
-            <td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ attribute.name }}">{{ attribute.name }}</span></code></td>
+            <td><code><autoref identifier="{{ obj.path }}.{{ attribute.name }}" optional hover>{{ attribute.name }}</autoref></code></td>
             <td class="doc-attribute-details">
               <div class="doc-md-description">
                 {{ attribute.description|convert_markdown(heading_level, html_id) }}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja
index d21db25e..a3b494c9 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja
@@ -32,7 +32,7 @@ Context:
       <tbody>
         {% for class in section.value %}
           <tr class="doc-section-item">
-            <td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ class.name }}">{{ class.name }}</span></code></td>
+            <td><code><autoref identifier="{{ obj.path }}.{{ class.name }}" optional hover>{{ class.name }}</autoref></code></td>
             <td>
               <div class="doc-md-description">
                 {{ class.description|convert_markdown(heading_level, html_id) }}
@@ -50,7 +50,7 @@ Context:
     <ul>
       {% for class in section.value %}
         <li class="doc-section-item field-body">
-          <b><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ class.name }}">{{ class.name }}</span></code></b>
+          <b><code><autoref identifier="{{ obj.path }}.{{ class.name }}" optional hover>{{ class.name }}</autoref></code></b>
           –
           <div class="doc-md-description">
             {{ class.description|convert_markdown(heading_level, html_id) }}
@@ -72,7 +72,7 @@ Context:
       <tbody>
         {% for class in section.value %}
           <tr class="doc-section-item">
-            <td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ class.name }}">{{ class.name }}</span></code></td>
+            <td><code><autoref identifier="{{ obj.path }}.{{ class.name }}" optional hover>{{ class.name }}</autoref></code></td>
             <td class="doc-class-details">
               <div class="doc-md-description">
                 {{ class.description|convert_markdown(heading_level, html_id) }}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja
index 89ce923f..efaf9a37 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja
@@ -33,7 +33,7 @@ Context:
         {% for function in section.value %}
           {% if not function.name == "__init__" or not config.merge_init_into_class %}
             <tr class="doc-section-item">
-              <td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ function.name }}">{{ function.name }}</span></code></td>
+              <td><code><autoref identifier="{{ obj.path }}.{{ function.name }}" optional hover>{{ function.name }}</autoref></code></td>
               <td>
                 <div class="doc-md-description">
                   {{ function.description|convert_markdown(heading_level, html_id) }}
@@ -53,7 +53,7 @@ Context:
       {% for function in section.value %}
         {% if not function.name == "__init__" or not config.merge_init_into_class %}
           <li class="doc-section-item field-body">
-            <b><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ function.name }}">{{ function.name }}</span></code></b>
+            <b><code><autoref identifier="{{ obj.path }}.{{ function.name }}" optional hover>{{ function.name }}</autoref></code></b>
             –
             <div class="doc-md-description">
               {{ function.description|convert_markdown(heading_level, html_id) }}
@@ -77,7 +77,7 @@ Context:
         {% for function in section.value %}
           {% if not function.name == "__init__" or not config.merge_init_into_class %}
             <tr class="doc-section-item">
-              <td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ function.name }}">{{ function.name }}</span></code></td>
+              <td><code><autoref identifier="{{ obj.path }}.{{ function.name }}" optional hover>{{ function.name }}</autoref></code></td>
               <td class="doc-function-details">
                 <div class="doc-md-description">
                   {{ function.description|convert_markdown(heading_level, html_id) }}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja
index 49fc9d80..caec690f 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja
@@ -32,7 +32,7 @@ Context:
       <tbody>
         {% for module in section.value %}
           <tr class="doc-section-item">
-            <td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ module.name }}">{{ module.name }}</span></code></td>
+            <td><code><autoref identifier="{{ obj.path }}.{{ module.name }}" optional hover>{{ module.name }}</autoref></code></td>
             <td>
               <div class="doc-md-description">
                 {{ module.description|convert_markdown(heading_level, html_id) }}
@@ -50,7 +50,7 @@ Context:
     <ul>
       {% for module in section.value %}
         <li class="doc-section-item field-body">
-          <b><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ module.name }}">{{ module.name }}</span></code></b>
+          <b><code><autoref identifier="{{ obj.path }}.{{ module.name }}" optional hover>{{ module.name }}</autoref></code></b>
           –
           <div class="doc-md-description">
             {{ module.description|convert_markdown(heading_level, html_id) }}
@@ -72,7 +72,7 @@ Context:
       <tbody>
         {% for module in section.value %}
           <tr class="doc-section-item">
-            <td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ module.name }}">{{ module.name }}</span></code></td>
+            <td><code><autoref identifier="{{ obj.path }}.{{ module.name }}" optional hover>{{ module.name }}</autoref></code></td>
             <td class="doc-module-details">
               <div class="doc-md-description">
                 {{ module.description|convert_markdown(heading_level, html_id) }}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
index 67f02bb3..f150afd1 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja
@@ -21,7 +21,7 @@ which is a tree-like structure representing a Python expression.
       annotation_path (str): Either "brief", "source", or "full".
 
   Returns:
-      Either a cross-reference (using an autorefs span) or the name itself.
+      Either a cross-reference (using an autoref element) or the name itself.
   -#}
   {%- with full = name.canonical_path -%}
     {%- if annotation_path == "brief" -%}
@@ -34,7 +34,7 @@ which is a tree-like structure representing a Python expression.
     {%- for title, path in annotation|split_path(full) -%}
       {%- if not signature or config.signature_crossrefs -%}
         {%- filter stash_crossref(length=title|length) -%}
-          <span data-autorefs-optional{% if title != path %}-hover{% endif %}="{{ path }}">{{ title }}</span>
+          <autoref identifier="{{ path }}" optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
         {%- endfilter -%}
       {%- else -%}
         {{ title }}