datajoint · MilagrosMarin · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -111,6 +111,7 @@ nav:
   - About:
       - about/index.md
       - History: about/history.md
+      - Documentation Versioning: about/versioning.md
       - Platform: https://www.datajoint.com/sign-up
       - Citation: about/citation.md
       - Publications: about/publications.md
@@ -180,6 +181,7 @@ plugins:
         - images/*md
         - "*/SUMMARY.md"
 markdown_extensions:
+  - admonition  # Enable !!! admonition blocks
   - attr_list
   - md_in_html
   - toc:

diff --git a/src/.overrides/main.html b/src/.overrides/main.html
@@ -1,5 +1,19 @@
 {% extends "base.html" %}
 
+{% block announce %}
+  <div class="md-banner">
+    <div class="md-banner__inner md-grid md-typeset">
+      <p>
+        📖 You are viewing documentation for <strong>DataJoint {{ config.extra.datajoint_version }}+</strong>
+        ·
+        <a href="{{ config.site_url }}how-to/migrate-to-v20/">
+          Migration guide for legacy users (pre-2.0)
+        </a>
+      </p>
+    </div>
+  </div>
+{% endblock %}
+
 {% block extrahead %}
 	<script
 		src="https://www.datadoghq-browser-agent.com/us1/v4/datadog-rum.js"

diff --git a/src/about/versioning.md b/src/about/versioning.md
@@ -0,0 +1,110 @@
+# Documentation Versioning
+
+This page explains how version information is indicated throughout the DataJoint documentation.
+
+## Documentation Scope
+
+**This documentation covers DataJoint 2.0 and later.** All code examples and tutorials use DataJoint 2.0+ syntax and APIs.
+
+**DataJoint 2.0 is the baseline.** Features and APIs introduced in 2.0 are documented without version markers, as they are the standard for this documentation.
+
+If you're using legacy DataJoint (version 0.14.x or earlier), please visit the [legacy documentation](https://datajoint.github.io/datajoint-python) or follow the [Migration Guide](../how-to/migrate-to-v20.md) to upgrade.
+
+## Version Indicators
+
+### Global Indicators
+
+**Site-wide banner:** Every page displays a banner indicating you're viewing documentation for DataJoint 2.0+, with a link to the migration guide for legacy users.
+
+**Footer:** The footer shows which version of DataJoint this documentation covers.
+
+### Feature-Level Indicators
+
+Version admonitions are used for features introduced **after 2.0** (i.e., version 2.1 and later):
+
+#### New Features
+
+!!! version-added "New in 2.1"
+
+    This indicates a feature that was introduced after the 2.0 baseline.
+
+**Example usage:**
+
+!!! version-added "New in 2.1"
+
+    The `dj.Top` operator with ordering support was introduced in DataJoint 2.1.
+
+**Note:** Features present in DataJoint 2.0 (the baseline) are not marked with version indicators.
+
+#### Changed Behavior
+
+!!! version-changed "Changed in 2.1"
+
+    This indicates behavior that changed in a post-2.0 release.
+
+**Example usage:**
+
+!!! version-changed "Changed in 2.1"
+
+    The `populate()` method now supports priority-based scheduling by default.
+
+    Use `priority=50` to control execution order when using `reserve_jobs=True`.
+
+#### Deprecated Features
+
+!!! version-deprecated "Deprecated in 2.1, removed in 3.0"
+
+    This indicates features that are deprecated and will be removed in future versions.
+
+**Example usage:**
+
+!!! version-deprecated "Deprecated in 2.1, removed in 3.0"
+
+    The `allow_direct_insert` parameter is deprecated. Use `dj.config['safemode']` instead.
+
+**Note:** Features deprecated at the 2.0 baseline (coming from pre-2.0) are documented in the [Migration Guide](../how-to/migrate-to-v20.md) rather than with admonitions, since this documentation assumes 2.0 as the baseline.
+
+### Inline Version Badges
+
+For features introduced **after 2.0**, inline version badges may appear in API reference:
+
+- `dj.Top()` <span class="version-badge">v2.1+</span> - Top N restriction with ordering
+- `some_method()` <span class="version-badge deprecated">deprecated</span> - Legacy method
+
+**Note:** Methods and features present in DataJoint 2.0 (the baseline) do not have version badges.
+
+## Checking Your Version
+
+To check which version of DataJoint you're using:
+
+```python
+import datajoint as dj
+print(dj.__version__)
+```
+
+- **Version 2.0 or higher:** You're on the current version
+- **Version 0.14.x or lower:** You're on legacy DataJoint
+
+## Migration Path
+
+If you're upgrading from legacy DataJoint (pre-2.0):
+
+1. **Review** the [What's New in 2.0](../explanation/whats-new-2.md) page to understand major changes
+2. **Follow** the [Migration Guide](../how-to/migrate-to-v20.md) for step-by-step upgrade instructions
+3. **Reference** this documentation for updated syntax and APIs
+
+## Legacy Documentation
+
+For DataJoint 0.x documentation, visit:
+
+**[datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python)**
+
+## Version History
+
+| Version | Release Date | Major Changes |
+|---------|--------------|---------------|
+| 2.0 | 2026 | Redesigned fetch API, unified stores, per-table jobs, semantic matching |
+| 0.14.x | 2020-2025 | Legacy version with external storage |
+| 0.13.x | 2019 | Legacy version |
+
+For complete version history, see the [changelog](https://github.com/datajoint/datajoint-python/releases).
diff --git a/src/assets/stylesheets/extra.css b/src/assets/stylesheets/extra.css
@@ -0,0 +1,134 @@
+/* ===================================================================
+   DataJoint Documentation Custom Styles
+   =================================================================== */
+
+/* -------------------------------------------------------------------
+   Version Banner (Site-wide)
+   ------------------------------------------------------------------- */
+
+.md-banner {
+  background-color: var(--md-primary-fg-color);
+  color: var(--md-primary-bg-color);
+  font-size: 0.7rem;
+  padding: 0.4rem 0;
+  text-align: center;
+}
+
+.md-banner__inner {
+  padding: 0;
+}
+
+.md-banner p {
+  margin: 0;
+  padding: 0;
+}
+
+.md-banner a {
+  color: var(--md-primary-bg-color);
+  text-decoration: underline;
+  font-weight: 500;
+}
+
+.md-banner a:hover {
+  text-decoration: none;
+}
+
+/* -------------------------------------------------------------------
+   Version Admonitions
+   ------------------------------------------------------------------- */
+
+/* New in version X.Y */
+.admonition.version-added {
+  border-left-color: #00c853;
+}
+
+.admonition.version-added > .admonition-title {
+  background-color: rgba(0, 200, 83, 0.1);
+}
+
+.admonition.version-added > .admonition-title::before {
+  background-color: #00c853;
+  content: "✨";
+}
+
+/* Changed in version X.Y */
+.admonition.version-changed {
+  border-left-color: #ff9800;
+}
+
+.admonition.version-changed > .admonition-title {
+  background-color: rgba(255, 152, 0, 0.1);
+}
+
+.admonition.version-changed > .admonition-title::before {
+  background-color: #ff9800;
+  content: "🔄";
+}
+
+/* Deprecated since version X.Y */
+.admonition.version-deprecated {
+  border-left-color: #f44336;
+}
+
+.admonition.version-deprecated > .admonition-title {
+  background-color: rgba(244, 67, 54, 0.1);
+}
+
+.admonition.version-deprecated > .admonition-title::before {
+  background-color: #f44336;
+  content: "⚠️";
+}
+
+/* -------------------------------------------------------------------
+   Inline Version Badges
+   ------------------------------------------------------------------- */
+
+.version-badge {
+  font-size: 0.7em;
+  padding: 0.2em 0.5em;
+  background-color: #2196F3;
+  color: white;
+  border-radius: 3px;
+  font-weight: 500;
+  vertical-align: middle;
+  white-space: nowrap;
+}
+
+.version-badge.deprecated {
+  background-color: #f44336;
+}
+
+.version-badge.new {
+  background-color: #00c853;
+}
+
+.version-badge.changed {
+  background-color: #ff9800;
+}
+
+/* -------------------------------------------------------------------
+   Code Block Enhancements
+   ------------------------------------------------------------------- */
+
+/* Add subtle visual distinction for code comparisons */
+.version-comparison {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  margin: 1rem 0;
+}
+
+.version-comparison > div {
+  padding: 0.5rem;
+  border-radius: 0.2rem;
+}
+
+.version-comparison .legacy {
+  background-color: rgba(244, 67, 54, 0.05);
+  border-left: 3px solid #f44336;
+}
+
+.version-comparison .current {
+  background-color: rgba(0, 200, 83, 0.05);
+  border-left: 3px solid #00c853;
+}
diff --git a/src/how-to/installation.md b/src/how-to/installation.md
@@ -2,6 +2,12 @@
 
 Install DataJoint Python and set up your environment.
 
+!!! warning "DataJoint 2.0+ Required"
+
+    This documentation is for **DataJoint 2.0 and later**. The PyPI and conda releases for DataJoint 2.0 are currently in preparation.
+
+    **If you install now, you may get an older version (0.14.x).** After installation, verify you have version 2.0 or later before following the tutorials and guides.
+
 ## Basic Installation
 
 ```bash
@@ -23,19 +29,35 @@ pip install datajoint[all]
 
 ## Development Installation
 
+To install the latest pre-release version:
+
 ```bash
-git clone https://github.com/datajoint/datajoint-python.git
+git clone -b pre/v2.0 https://github.com/datajoint/datajoint-python.git
 cd datajoint-python
 pip install -e ".[dev]"
 ```
 
 ## Verify Installation
 
+**Important:** Check that you have DataJoint 2.0 or later:
+
 ```python
 import datajoint as dj
 print(dj.__version__)
 ```
 
+**Expected output:** `2.0.0` or higher
+
+!!! danger "Version Mismatch"
+
+    If you see version `0.14.x` or lower, you have the legacy version of DataJoint. This documentation will not match your installed version.
+
+    **Options:**
+
+    1. **Upgrade to 2.0 (pre-release):** Install from the `pre/v2.0` branch (see Development Installation above)
+    2. **Use legacy documentation:** Visit [datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python)
+    3. **Migrate existing pipeline:** Follow the [Migration Guide](migrate-to-v20.md)
+
 ## Database Server
 
 DataJoint requires a MySQL-compatible database server:

diff --git a/src/index.md b/src/index.md
@@ -1,8 +1,10 @@
 # DataJoint Documentation
 
-> **DataJoint 2.0 is a major release.** Existing pipelines require migration.
-> See the [Migration Guide](how-to/migrate-to-v20.md) for upgrade instructions.
-> For pre-2.0 documentation, visit [datajoint.github.io/datajoint-python](https://datajoint.github.io/datajoint-python).
+!!! info "Documentation for DataJoint 2.0+"
+
+    Python code examples in this documentation use DataJoint 2.0 syntax. If you're using DataJoint pre-2.0, see the [Migration Guide](how-to/migrate-to-v20.md) or visit [legacy docs](https://datajoint.github.io/datajoint-python).
+
+## About DataJoint
 
 **DataJoint** is a framework for scientific data pipelines built on the [Relational Workflow Model](explanation/relational-workflow-model.md)—a paradigm where your database schema is an executable specification of your workflow.