jothepro · ReenigneArcher · Aug 7, 2024 · Sep 5, 2024 · Mar 21, 2026 · Mar 21, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 docs/html
+_readthedocs
 .DS_Store
 .idea
 

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,19 @@
+---
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "miniconda-latest"
+  commands:
+    - chmod +x readthedocs_build.sh
+    - ./readthedocs_build.sh
+
+# using conda, we can get newer doxygen and graphviz than ubuntu provide
+# https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661
+conda:
+  environment: environment.yml
diff --git a/docs/extensions.md b/docs/extensions.md
@@ -238,6 +238,45 @@ Each item in the list must start with an element that has the class `tab-title`.
 </div>
 ```
 
+## Read the Docs search {#readthedocs-search}
+
+Use search index from Read the Docs instead of the built-in doxygen search. This allows using search metrics from
+Read the Docs and in general gives a better search experience.
+
+### Installation
+
+1. Add the required resources in your `Doxyfile`:
+   - **HTML_EXTRA_FILES:** `doxygen-awesome-readthedocs-search.js`
+   - **HTML_EXTRA_STYLESHEET:** `doxygen-awesome-readthedocs-search.css`
+   - **SEARCHENGINE:** `YES`
+   - **SERVER_BASED_SEARCH:** `YES`
+   - **EXTERNAL_SEARCH:** `YES`
+   - **SEARCHENGINE_URL:** `https://<your-project>.readthedocs.io/` OR
+   - **SEARCHENGINE_URL:** `https://<your-custom-readthedocs-domain>/`
+
+   `SEARCHENGINE_URL` is only used when testing locally, otherwise the domain name is detected automatically.
+   When testing locally, search may not work without disabling CORS. This can be a security risk, so it is advised to
+   only test inside of Read the Docs.
+
+2. In the `header.html` template, include `doxygen-awesome-readthedocs-search.js` at the end of the `<head>` and then initialize it:
+    ```html
+   <html> 
+       <head>
+           <!-- ... other metadata & script includes ... -->
+           <script type="text/javascript" src="$relpath^doxygen-awesome-readthedocs-search.js"></script>
+           <script type="text/javascript">
+               DoxygenAwesomeReadtheDocsSearch.init()
+           </script>
+       </head>
+       <body>
+    ```
+   For the sidebar-only theme variant, initialize with left-aligned live results:
+    ```html
+   <script type="text/javascript">
+       DoxygenAwesomeReadtheDocsSearch.init('leftAlign')
+   </script>
+    ```
+
 ## Page Navigation {#extension-page-navigation}
 
 @warning Experimental feature! Please report bugs [here](https://github.com/jothepro/doxygen-awesome-css/issues).
@@ -281,4 +320,4 @@ The following conditions must be met for the feature to work properly:
 | Previous          |                              Next |
 |:------------------|----------------------------------:|
 | [Home](README.md) | [Customization](customization.md) |
-</div>
+</div>
diff --git a/doxygen-awesome-readthedocs-search.css b/doxygen-awesome-readthedocs-search.css
@@ -0,0 +1,103 @@
+/* Highlight text in search results */
+span.highlighted {
+    background-color:var(--warning-color);
+    color: var(--page-foreground-color);
+    padding: 2px;
+    border-radius: 3px;
+}
+
+/* Remove list bullets for search results */
+ul.search {
+    list-style-type: none;
+    padding: 0;
+}
+
+/* Add horizontal divider for search results */
+ul.search li.search-result {
+    border-bottom: 1px solid var(--separator-color);
+    padding-bottom: 10px;
+    margin-bottom: 10px;
+}
+
+/* Live search dropdown */
+#RTDLiveResults {
+    margin-top: var(--spacing-small);
+    display: none;
+    position: absolute;
+    z-index: 10000;
+    left: unset;
+    background: var(--page-background-color);
+    border: 1px solid var(--separator-color);
+    border-radius: var(--border-radius-large);
+    box-shadow: var(--box-shadow);
+    max-height: 420px;
+    overflow-y: auto;
+}
+
+@media screen and (max-width: 767px) {
+    #RTDLiveResults {
+        left: var(--spacing-medium);
+        right: var(--spacing-medium);
+    }
+}
+
+#RTDLiveResults .rtd-live-list {
+    list-style: none;
+    margin: 0;
+    padding: var(--spacing-small) 0;
+}
+
+#RTDLiveResults .rtd-live-list li {
+    margin: 0;
+}
+
+#RTDLiveResults .rtd-live-item {
+    display: block;
+    padding: var(--spacing-small) var(--spacing-medium);
+    margin: var(--spacing-small);
+    border-radius: var(--border-radius-small);
+    color: var(--page-foreground-color);
+    text-decoration: none;
+    outline: none;
+}
+
+#RTDLiveResults .rtd-live-item:hover,
+#RTDLiveResults .rtd-live-item:focus {
+    background: var(--menu-focus-background);
+}
+
+#RTDLiveResults .rtd-live-title {
+    display: block;
+    font-weight: bold;
+    font-size: var(--navigation-font-size);
+}
+
+#RTDLiveResults .rtd-live-snippet {
+    display: block;
+    font-size: calc(var(--navigation-font-size) * 0.9);
+    color: var(--page-secondary-foreground-color);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 400px;
+}
+
+#RTDLiveResults .rtd-live-item:hover .rtd-live-title,
+#RTDLiveResults .rtd-live-item:hover .rtd-live-snippet,
+#RTDLiveResults .rtd-live-item:focus .rtd-live-title,
+#RTDLiveResults .rtd-live-item:focus .rtd-live-snippet {
+    color: var(--menu-focus-foreground);
+}
+
+#RTDLiveResults .rtd-live-snippet mark {
+    background-color: var(--warning-color);
+    color: var(--page-foreground-color);
+    padding: 0 2px;
+    border-radius: 2px;
+}
+
+#RTDLiveResults .rtd-live-empty {
+    padding: var(--spacing-medium);
+    color: var(--page-secondary-foreground-color);
+    font-size: var(--navigation-font-size);
+}