diff --git a/docs/_extension/component_directive.py b/docs/_extension/component_directive.py
new file mode 100644
index 000000000..1749b0e7a
--- /dev/null
+++ b/docs/_extension/component_directive.py
@@ -0,0 +1,98 @@
+"""A directive to generate the list of all the built-in components.
+
+Read the content of the component folder and generate a list of all the components.
+This list will display some informations about the component and a link to the
+GitHub file.
+"""
+import re
+from pathlib import Path
+from typing import Any, Dict, List
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+
+logger = logging.getLogger(__name__)
+
+
+class ComponentListDirective(SphinxDirective):
+ """A directive to generate the list of all the built-in components.
+
+ Read the content of the component folder and generate a list of all the components.
+ This list will display some informations about the component and a link to the
+ GitHub file.
+ """
+
+ name = "component-list"
+ has_content = True
+ required_arguments = 0
+ optional_arguments = 0
+ final_argument_whitespace = True
+
+ def run(self) -> List[nodes.Node]:
+ """Create the list."""
+ # get the list of all th jinja templates
+ # not that to remain compatible with sphinx they are labeled as html files
+ root = Path(__file__).parents[2]
+ component_dir = (
+ root
+ / "src"
+ / "pydata_sphinx_theme"
+ / "theme"
+ / "pydata_sphinx_theme"
+ / "components"
+ )
+ if not component_dir.is_dir():
+ raise FileNotFoundError(
+ f"Could not find component folder at {component_dir}."
+ )
+ components = sorted(component_dir.glob("*.html"))
+
+ # create the list of all the components description using bs4
+ # at the moment we use dummy information
+ docs = []
+ pattern = re.compile(r"(?<={#).*?(?=#})", flags=re.DOTALL)
+ for c in components:
+ comment = pattern.findall(c.read_text())
+ docs.append(comment[0].strip() if comment else "No description available.")
+
+ # get the urls from the github repo latest branch
+ github_url = "https://github.com/pydata/pydata-sphinx-theme/blob/main"
+ urls = [
+ f"{github_url}/{component.relative_to(root)}" for component in components
+ ]
+
+ # build the list of all the components
+ items = []
+ for component, url, doc in zip(components, urls, docs):
+ items.append(
+ nodes.list_item(
+ "",
+ nodes.paragraph(
+ "",
+ "",
+ nodes.reference("", component.stem, internal=False, refuri=url),
+ nodes.Text(f": {doc}"),
+ ),
+ )
+ )
+
+ return [nodes.bullet_list("", *items)]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+ """Add custom configuration to sphinx app.
+
+ Args:
+ app: the Sphinx application
+
+ Returns:
+ the 2 parallel parameters set to ``True``.
+ """
+ app.add_directive("component-list", ComponentListDirective)
+
+ return {
+ "parallel_read_safe": True,
+ "parallel_write_safe": True,
+ }
diff --git a/docs/conf.py b/docs/conf.py
index fdcaec9bd..0a9076c64 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -34,6 +34,9 @@
"sphinx_design",
"sphinx_copybutton",
"autoapi.extension",
+ # custom extentions
+ "_extension.gallery_directive",
+ "_extension.component_directive",
# For extension examples and demos
"myst_parser",
"ablog",
@@ -44,8 +47,6 @@
"sphinx_togglebutton",
"jupyterlite_sphinx",
"sphinx_favicon",
- # custom extentions
- "_extension.gallery_directive",
]
jupyterlite_config = "jupyterlite_config.json"
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 7372ad980..f57cfd3b7 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -518,29 +518,12 @@ Below is a list of built-in templates that you can insert into any section.
Note that some of them may have CSS rules that assume a specific section (and
will be named accordingly).
-.. refer to files in: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/
-
-- ``breadcrumbs.html``
-- ``copyright.html``
-- ``edit-this-page.html``
-- ``footer-article/prev-next.html``
-- ``icon-links.html``
-- ``last-updated.html``
-- ``navbar-icon-links.html``
-- ``navbar-logo.html``
-- ``navbar-nav.html``
-- ``page-toc.html``
-- ``searchbox.html``
-- ``search-button.html``
-- ``search-field.html``
-- ``sidebar-ethical-ads.html``
-- ``sidebar-nav-bs.html``
-- ``sourcelink.html``
-- ``sphinx-version.html``
-- ``theme-switcher.html``
-- ``version-switcher.html``
-- ``indices.html``
-- ``theme-version.html``
+.. note::
+
+ When adding/changing/overwritting a component, the ".html" suffix is optional.
+ That's why all of them are displayed without it in the following list.
+
+.. component-list::
Add your own HTML templates to theme sections
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html
index c9e6f0438..8b5595bf3 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html
@@ -1,3 +1,4 @@
+{# Displays (and links to) the parent section(s) of the currently viewed page. #}
{%- block breadcrumbs %}
{#
If we have more than 3 parents (excluding the home page) then we remove
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html
index 8e1449d7d..b3e4f14e2 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html
@@ -1,3 +1,4 @@
+{# Displays the copyright information (which is defined in conf.py). #}
{% if show_copyright and copyright %}
{% if hasdoc('copyright') %}
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/edit-this-page.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/edit-this-page.html
index 5bc0f1fca..fcfbf08ab 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/edit-this-page.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/edit-this-page.html
@@ -1,3 +1,4 @@
+{# Displays a link to the edit interface of the page source in the specified Version Control System. #}
{% if sourcename is defined and theme_use_edit_page_button==true and page_source_suffix %}
{% set src = sourcename.split('.') %}
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html
index fe9faf52a..0b6ce64ad 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html
@@ -1,3 +1,4 @@
+{# Displays icon-links as list items. #}
{%- macro icon_link_nav_item(url, icon, name, type, attributes='') -%}
{%- if url | length > 2 %}
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/indices.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/indices.html
index dc7090a78..73de5b33f 100644
--- a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/indices.html
+++ b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/indices.html
@@ -1,3 +1,4 @@
+{# Displays links to the Sphinx-generated indices (genindex, modindex, py-modindex). #}