diff --git a/README.md b/README.md
index 38807954..9eaf1e29 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,15 @@ Cloud-friendly access to archival data
 [![Pypi](https://img.shields.io/pypi/v/kerchunk.svg)](https://pypi.python.org/pypi/kerchunk/)
 [![Conda-forge](https://img.shields.io/conda/vn/conda-forge/kerchunk.svg)](https://anaconda.org/conda-forge/kerchunk)
 
+> **Note:** Kerchunk is in maintenance mode. No new features are planned, though bug
+> fixes will continue to be accepted. For new projects, we recommend
+> [VirtualiZarr](https://virtualizarr.readthedocs.io/) for creating virtual Zarr
+> datasets, together with [Icechunk](https://icechunk.io/) as the storage engine.
+> See the FAQ for a
+> [comparison of libraries](https://virtualizarr.readthedocs.io/en/stable/explanation/faq.html#how-do-the-virtualizarr-and-kerchunk-libraries-compare),
+> [comparison of supported storage formats](https://virtualizarr.readthedocs.io/en/stable/explanation/faq.html#which-format-should-i-save-my-virtual-references-as),
+> and for how to [migrate existing Kerchunk references](https://virtualizarr.readthedocs.io/en/stable/explanation/faq.html#i-have-already-kerchunked-my-data-do-i-have-to-redo-that).
+
 Kerchunk is a library that provides a unified way to represent a variety of chunked, compressed
 data formats (e.g. NetCDF, HDF5, GRIB),
 allowing efficient access to the data from traditional file systems or cloud object storage.
diff --git a/docs/source/_static/maintenance_banner.css b/docs/source/_static/maintenance_banner.css
new file mode 100644
index 00000000..c2d4dfeb
--- /dev/null
+++ b/docs/source/_static/maintenance_banner.css
@@ -0,0 +1,38 @@
+#kerchunk-maintenance-banner {
+    position: relative;
+    z-index: 10000;
+    background: #fff3cd;
+    color: #664d03;
+    border-bottom: 1px solid #ffecb5;
+    padding: 20px 50px 20px 20px;
+    font-size: 1rem;
+    line-height: 1.5;
+    text-align: center;
+}
+
+#kerchunk-maintenance-banner-content {
+    max-width: 1100px;
+    margin: 0 auto;
+}
+
+#kerchunk-maintenance-banner-title {
+    font-size: 1.15em;
+}
+
+#kerchunk-maintenance-banner a {
+    color: #664d03;
+    text-decoration: underline;
+}
+
+#kerchunk-maintenance-banner button {
+    position: absolute;
+    top: 50%;
+    right: 10px;
+    transform: translateY(-50%);
+    background: none;
+    border: none;
+    font-size: 2.2rem;
+    line-height: 1;
+    cursor: pointer;
+    color: #664d03;
+}
diff --git a/docs/source/_static/maintenance_banner.js b/docs/source/_static/maintenance_banner.js
new file mode 100644
index 00000000..c1c6b816
--- /dev/null
+++ b/docs/source/_static/maintenance_banner.js
@@ -0,0 +1,46 @@
+(function () {
+    var DISMISS_KEY = "kerchunkMaintenanceBannerDismissed";
+
+    try {
+        if (localStorage.getItem(DISMISS_KEY) === "1") {
+            return;
+        }
+    } catch (e) {
+        // localStorage unavailable (e.g. private browsing); show the banner anyway.
+    }
+
+    document.addEventListener("DOMContentLoaded", function () {
+        var banner = document.createElement("div");
+        banner.id = "kerchunk-maintenance-banner";
+
+        var content = document.createElement("div");
+        content.id = "kerchunk-maintenance-banner-content";
+        content.innerHTML =
+            '<strong id="kerchunk-maintenance-banner-title">Kerchunk is in maintenance mode: no new features are planned, ' +
+            "though bug fixes will continue to be accepted.</strong><br><br>" +
+            "For new projects, we recommend " +
+            '<a href="https://virtualizarr.readthedocs.io/">VirtualiZarr</a> for creating ' +
+            "virtual Zarr datasets, together with " +
+            '<a href="https://icechunk.io/">Icechunk</a> as the storage engine.<br><br>' +
+            'See the FAQ for a <a href="https://virtualizarr.readthedocs.io/en/stable/explanation/faq.html#how-do-the-virtualizarr-and-kerchunk-libraries-compare">comparison of libraries</a>, ' +
+            '<a href="https://virtualizarr.readthedocs.io/en/stable/explanation/faq.html#which-format-should-i-save-my-virtual-references-as">comparison of supported storage formats</a>, ' +
+            "and for how to " +
+            '<a href="https://virtualizarr.readthedocs.io/en/stable/explanation/faq.html#i-have-already-kerchunked-my-data-do-i-have-to-redo-that">migrate existing Kerchunk references</a>.';
+        banner.appendChild(content);
+
+        var dismiss = document.createElement("button");
+        dismiss.setAttribute("aria-label", "Dismiss");
+        dismiss.textContent = "×";
+        dismiss.addEventListener("click", function () {
+            banner.remove();
+            try {
+                localStorage.setItem(DISMISS_KEY, "1");
+            } catch (e) {
+                // ignore
+            }
+        });
+        banner.appendChild(dismiss);
+
+        document.body.insertBefore(banner, document.body.firstChild);
+    });
+})();
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 23d479cd..a43e187b 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -53,7 +53,9 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['images']
+html_static_path = ['images', '_static']
+html_css_files = ['maintenance_banner.css']
+html_js_files = ['maintenance_banner.js']
 pygments_style = "sphinx"
 html_theme = "sphinx_rtd_theme"
 html_logo = "kerchunk.png"