apache · espy · May 11, 2026 · May 11, 2026 · May 11, 2026 · May 11, 2026
diff --git a/WEBSITE_README.md b/WEBSITE_README.md
@@ -0,0 +1,42 @@
+# Information about editing and building the PouchDB website
+
+- The PouchDB website is an [eleventy](https://www.11ty.dev/) site that lives in the `/docs` folder.
+- You build it with `$npm run build-site`. This will start a dev server of sorts, with the site running at [localhost:4000](htt://localhost:4000). The site will rebuild if you change any template or style files. You still need to refresh the browser yourself. The site is built into `/docs/_site`.
+- Deployment is automatic, whatever lands in the `master` branch is deployed by a github workflow.
+
+## How to update docs for a new feature
+
+When you write a new PouchDB feature, document it in `/docs/version/latest`. This will become part of the `stable` docs as soon as the next release is cut.
+
+## How to update the docs for a new PouchDB release
+
+When you cut a new PouchDB release, complete this checklist:
+
+- [ ] Add the new version to the `/docs/_data/versions.js` file
+- [ ] _Copy_ (not rename) the `/docs/version/latest` folder to `/docs/version/<newPouchDBVersion>`
+
+That’s it.
+
+## Documentation Structure
+
+The site has versioned docs as of 2026. This means that parts of the site are different depending on which version you’re looking at them for: the `api` section, the `guides` section, and the `learn` section. Basically everything that isn’t the start page or the blog. These docs are written by hand, not autogenerated from the PouchDB source. So whenever you change PouchDB itself, you also need to update the docs.
+
+We define the documented versions in `/docs/_data/versions.js`. This makes two global vars available:
+- `versions.all`: an array of versions we have different docs for, e.g. `['7.0.0', '8.0.0', '9.0.0']`
+- `versions.stable`: the version number of the last release, e.g. `9.0.0`
+
+Versioned docs are kept in `/docs/version/<versionNumber>`, and we version like this:
+
+- `latest`: Lives in `/docs/version/latest`. This is a special folder that isn’t tied to a release. All doc updates that concern the _next_ release must be made in here.
+- Versioned docs, for example those for version `10.0.0` live in `/docs/version/10.0.0`. This folder should be created as part of the `10.0.0` release and is simply a copy of `/docs/version/latest`. This means over time there will be `/docs/version/9.0.0`, `/docs/version/10.0.0`, `/docs/version/10.1.0` and so on.
+- `stable`: Another special case. This lives nowhere in the site source, but is generated by Eleventy at build time. It takes the contents of `/docs/version/<versions.stable>`, and copies them over to `/`, so the docs at the root of the site are always for the most recent (stable) release. This also preserves any existing links to the unversioned docs we used to have.
+
+This means that if `versions.stable` is `9.0.0`:
+
+- `http://pouchdb.com/api.html` displays `/docs/version/9.0.0/api.html`
+- `http://pouchdb.com/guides/setup-couchdb.html` displays `/docs/version/9.0.0/guides/setup-couchdb.md`
+- `http://pouchdb.com/version/7.0.0/guides/setup-pouchdb.html/` displays `/docs/version/7.0.0/guides/setup-couchdb.md`
+
+To make this re-use of the stable docs possible, we need to jump through two hoops:
+1. Generate the root-level docs from version docs, this is done in `/docs/stable.liquid` and utilises [11ty’s pagination feature](https://www.11ty.dev/docs/pages-from-data/) to iterate over the stable version docs and output them in root.
+2. All sidebar links at root level need to be modified to strip the `/version/<versionNumber>` fragment, this is done with the `makeURLForStable` filter in `/eleventy.config.js`.
diff --git a/docs/404.md b/docs/404.md
@@ -0,0 +1,23 @@
+---
+title: Couldn’t find that page, sorry.
+permalink: 404.html
+layout: default.html
+edit: false
+---
+
+<div class="band band-inverse">
+  <div class="container">
+    <div class="row">
+      <div class='col-sm-9'>
+
+What could have happened:
+
+- A typo or a broken link. Best back to the [home page](/) and start over.
+- If you came to this page from the documentation version switcher, you might have been viewing docs for a feature that doesn’t exist in the version you switched to.
+- Something on the page is broken. If you’re sure this is the case, please [open an issue](https://github.com/apache/pouchdb/issues) so we can fix it. If _you_ want to fix it, please [open a PR at our GitHub repo](https://github.com/apache/pouchdb).
+
+👋 Have a good day!
+      </div>
+    </div>
+  </div>
+</div>
diff --git a/docs/WEBSITE_README.md b/docs/WEBSITE_README.md
@@ -34,18 +34,18 @@ By default, SW will only cache the pages you’ve seen plus `offline.html`, whic
 
 To test the "Content updated, reload now?" toast that indicates that a new version of the site is available, run the dev server, make a change to the site (e.g. change some text somewhere), then navigate once or reload the page with a normal (not hard) reload. The update toast should show. When you click it, the page and the serviceworker cache will be updated.
 
-## PouchDB Version Updates
+## PouchDB Version Update Checklist
 
 If you’re releasing a new PouchDB version, the site also needs some updates:
 
-1. Replace `docs/static/js/pouchdb.min.js` with your newly built version of the same file (this is the PouchDB that is hosted by the website itself and available in the browser dev console).
-2. Update the `version` key in `docs/_data/site.js` to the new PouchDB version.
+- [ ] Replace `docs/static/js/pouchdb.min.js` with your newly built version of the same file (this is the PouchDB that is hosted by the website itself and available in the browser dev console).
+- [ ] Update the `version` key in `docs/_data/site.js` to the new PouchDB version.
 
 Then deploy the webite.
 
 ## Website Deployment
 
-Currently, the website is deployed manually by members of the team. In the near future, any website changes merged into `master` will be deployed automatically.
+Any website changes merged into `master` will be deployed to https://pouchdb.apache.org automatically.
 
 ## Technology Choices
 

diff --git a/docs/_data/versions.js b/docs/_data/versions.js
@@ -0,0 +1,18 @@
+/*
+
+Gives us globally available info about PouchDB versions:
+
+- versions.all
+- versions.stable
+
+*/
+
+module.exports = () => {
+  const versions = ["7.3.0", "8.0.0", "9.0.0"];
+  return {
+    all: versions,
+    stable: versions.sort((a, b) =>
+      a.localeCompare(b, undefined, { numeric: true })
+    ).at(-1)
+  };
+};
diff --git a/docs/_includes/2ColLeft.html b/docs/_includes/2ColLeft.html
@@ -2,20 +2,30 @@
 layout: default.html
 ---
 
+{% if sidebar == "./nav.html" %}
+  {% assign sidebarIncludePath = "." | append: versionURLPrefix | append: '/nav.html' %}
+  {% unless version %}
+    {% assign sidebarIncludePath = "./version/" | append: versions.stable | append: '/nav.html' %}
+  {% endunless %}
+{% else %}
+  {% assign sidebarIncludePath = sidebar %}
+{% endif %}
+
 <article class="band">
   <div class="container">
     <div class="row">
         <div id="sidebar" class="col-sm-3 nav-sidebar-wrapper">
           <ul class="nav nav-silent nav-sidebar" role="navigation">
-            {% include {{sidebar}} %}
+            {% include {{sidebarIncludePath}} %}
           </ul>
         </div>
 
         <div class="col-sm-9" role="main">
+          {% include oldDocsWarning.html %}
           {{content}}
         <div>
-
-    </div>
-
+            
+      </div>
+      {% include versionSwitcher.html %}
   </div>
 </article>
diff --git a/docs/_includes/guide.html b/docs/_includes/guide.html
@@ -4,7 +4,8 @@
 
 {{ content }}
 
-{% assign guides = collections.guides | sort: 'data.index' %}
+{% assign guidesForVersion = collections.guides | byVersion: version %}
+{% assign guides = guidesForVersion | sort: 'data.index' %}
 {% for guide in guides %}
     {% if title == guide.data.title %}
         {% assign prev = guide.data.index | minus: 2 %}
@@ -13,12 +14,12 @@
         <ul class="pager">
             {% unless prev == -1 %}
                 <li class="previous">
-                    <a href="{{ guides[prev].url }}">&larr; {{ guides[prev].data.title }}</a>
+                    <a href="{{ guides[prev].url | makeURLForStable: version}}">&larr; {{ guides[prev].data.title }}</a>
                 </li>
             {% endunless %}
             {% if guides[next] %}
                 <li class="next">
-                    <a href="{{ guides[next].url }}">{{ guides[next].data.title }} &rarr;</a>
+                    <a href="{{ guides[next].url | makeURLForStable: version}}">{{ guides[next].data.title }} &rarr;</a>
                 </li>
             {% endif %}
         </ul>

diff --git a/docs/_includes/guides_nav.html b/docs/_includes/guides_nav.html
@@ -1,4 +1,5 @@
-{% for guide in collections.guides %}
+{% assign guides = collections.guides | byVersion: version %}
+{% for guide in guides %}
     {% assign title = guide.data.title %}
     {% if guide.data.nav %}
         {% assign title = guide.data.nav %}

diff --git a/docs/_includes/nav.html b/docs/_includes/nav.html
diff --git a/docs/_includes/nav_item.html b/docs/_includes/nav_item.html
@@ -1,3 +1,3 @@
 <li {% if page.url == include.path %} class="active" {% endif %}>
-    <a href="{{ site.baseurl }}{{ include.path | replace:'index.html','' }}">{{ include.text }}</a>
+    <a href="{{ site.baseurl }}{{include.versionPrefix}}{{ include.path | replace:'index.html','' | makeURLForStable: version}}">{{ include.text }}</a>
 </li>
diff --git a/docs/_includes/oldDocsWarning.html b/docs/_includes/oldDocsWarning.html
@@ -0,0 +1,13 @@
+<!-- `version` only exists if we’re on a /version/<versionnumber> URL -->
+{% if version and version != versions.stable %}
+  <div class="old-docs-warning">
+    <div class="alert alert-warning">
+      {% assign upToDateURL = page.url | makeURLForStable %}
+      <div class="alert-text"><p>✋ These are the docs for PouchDB version <code>{{version}}</code>. The current stable release is <a href="{{upToDateURL}}">{{versions.stable}}</a>.</p>
+      {% if version == 'latest'%}
+        <p>These docs are only relevant if you are building from source.</p>
+      {% endif %}
+      </div>
+    </div>
+  </div>
+{% endif %}
diff --git a/docs/_includes/versionSwitcher.html b/docs/_includes/versionSwitcher.html
@@ -0,0 +1,27 @@
+<!-- 
+ `version` only exists if we’re on a /version/<versionnumber> URL 
+  Currently still uses Bootstrap 3.1.1 dropdowns, see:
+  https://bootstrapdocs.com/v3.1.1/docs/components/#btn-dropdowns
+  https://bootstrapdocs.com/v3.1.1/docs/javascript/#dropdowns
+-->
+{% if version %}
+  {% assign currentVersion = version %}
+{% else %}
+  {% assign currentVersion = "Stable (" | append: versions.stable | append: ")" %}
+{% endif %}
+<div class="version-switcher">
+  <div class="btn-group dropdown dropup">
+    <button type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+      Version: {{currentVersion}} <span class="caret"></span>
+    </button>
+    <ul class="dropdown-menu" role="menu">
+      <li class="stable"><a href="{{ page.url | makeURLForStable }}">Stable ({{versions.stable}})</a></li>
+      <li role="separator" class="divider"></li>
+      {% for v in versions.all reversed %}
+        <li><a href="{{ page.url | transformDocURL: v }}">{{v}}</a></li>
+      {% endfor %}
+      <li role="separator" class="divider"></li>
+      <li><a href="{{ page.url | transformDocURL: 'latest' }}">Latest</a></li>
+    </ul>
+  </div>
+</div>
diff --git a/docs/api.html b/docs/api.html
diff --git a/docs/src/less/bootstrap/mixins.less b/docs/src/less/bootstrap/mixins.less
@@ -33,7 +33,8 @@
   outline: thin dotted;
   // WebKit
   // outline: 5px auto -webkit-focus-ring-color;
-  outline: 5px auto #de061b;
+  // outline: 5px auto #de061b;
+  outline: 5px auto currentColor;
   outline-offset: -2px;
 }
 

diff --git a/docs/src/less/pouchdb/alerts.less b/docs/src/less/pouchdb/alerts.less
@@ -46,3 +46,9 @@
   background-color: lighten(@alert-danger-bg, 3%);
   color: @alert-danger-text;
 }
+
+.old-docs-warning {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+}
diff --git a/docs/src/less/pouchdb/navs.less b/docs/src/less/pouchdb/navs.less
@@ -30,11 +30,14 @@
 }
 
 .nav-sidebar {
+  > li > a {
+    border-right: 2px solid transparent;
+    padding-right: 10px;
+  }
   > li.active > a,
   > li > a:hover {
     color: darken(@brand-primary, 10%);
     border-right: 2px solid lighten(@brand-primary, 10%);
-    padding-right: 10px;
   }
 }
 
@@ -66,7 +69,7 @@
 }
 
 @media (max-width: @screen-sm-min) {
-  .nav-sidebar-wrapper { position: static; }
+  .nav-sidebar-wrapper { position: static !important; } /* !important used to override stickyfill */
   .nav.nav-sidebar { margin-bottom: 25px; }
   .nav-head,
   .nav.nav-sidebar { text-align: center; }
@@ -95,7 +98,6 @@
   color: #eee;
   padding-bottom: 15px;
   margin-bottom: -15px;
-  z-index: 1;
 }
 .nav-code > li > a:hover {
   border-color: transparent;

diff --git a/docs/src/less/pouchdb/pouchdb.less b/docs/src/less/pouchdb/pouchdb.less
@@ -27,6 +27,7 @@
 @import "@{bootstrap}/dropdowns.less";
 @import "@{bootstrap}/pager.less";
 @import "@{bootstrap}/tooltip.less";
+@import "@{bootstrap}/dropdowns.less";
 
 // Utility classes
 @import "@{bootstrap}/responsive-utilities.less";
@@ -48,3 +49,4 @@
 @import "icons.less";
 @import "block.less";
 @import "icon-edit.less";
+@import "version-switcher.less";
diff --git a/docs/src/less/pouchdb/version-switcher.less b/docs/src/less/pouchdb/version-switcher.less
@@ -0,0 +1,12 @@
+.version-switcher {
+  position: fixed;
+  bottom: 2em;
+  right: 2em;
+  z-index: 1000;
+  .btn {
+    padding-inline: 1em;
+  }
+  .stable {
+    font-weight: bold;
+  }
+}
diff --git a/docs/stable.liquid b/docs/stable.liquid
@@ -0,0 +1,13 @@
+---
+pagination:
+  data: collections.stable
+  size: 1
+  alias: doc
+permalink: "{{ doc.data.page.url | makeURLForStable }}/"
+eleventyComputed:
+  layout: "{{ doc.data.layout }}"
+  title: "{{ doc.data.title }}"
+  sidebar: "{{ doc.data.sidebar }}"
+  edit: {{ doc.data.edit | boolean }}
+---
+{{ doc.templateContent }}
diff --git a/docs/adapters.md → docs/version/7.3.0/adapters.md b/docs/adapters.md → docs/version/7.3.0/adapters.md
@@ -1,7 +1,7 @@
 ---
 layout: 2ColLeft.html
 title: Adapters
-sidebar: nav.html
+sidebar: ./nav.html
 ---
 
 PouchDB is not a self-contained database; it is a CouchDB-style abstraction layer over other databases. By default, PouchDB ships with the [IndexedDB][] adapter for the browser, and a [LevelDB][] adapter in Node.js. This can be visualized as so: