DynamoDS · Copilot · Jan 26, 2026 · Jan 26, 2026 · Jan 26, 2026 · Jan 26, 2026
diff --git a/...ing_for_dynamo/6-0-updating-your-packages-and-dynamo-libraries-for-dynamo-2x.md b/...ing_for_dynamo/6-0-updating-your-packages-and-dynamo-libraries-for-dynamo-2x.md
@@ -1,5 +1,13 @@
 # Updating your Packages and Dynamo Libraries for Dynamo 2.x
 
+{% hint style="info" %}
+**Applies to**: Dynamo 2.x (2.0 - 2.19)  
+**Target Runtime**: .NET Framework 4.8  
+**File Format**: JSON (transitioned from XML)
+
+For other versions, see: [Dynamo 3.x Migration](6-1-updating-your-packages-and-dynamo-libraries-for-dynamo-3x-Net8.md) | [Dynamo 4.x Migration](6-2-updating-your-packages-and-dynamo-libraries-for-dynamo-4x.md)
+{% endhint %}
+
 ### Introduction: <a href="#introduction" id="introduction"></a>
 
 Dynamo 2.0 is a major release and some APIs have been changed or removed. One of the largest changes that will effect node and package authors is our move to a JSON file format.

diff --git a/...or_dynamo/6-1-updating-your-packages-and-dynamo-libraries-for-dynamo-3x-Net8.md b/...or_dynamo/6-1-updating-your-packages-and-dynamo-libraries-for-dynamo-3x-Net8.md
@@ -1,5 +1,13 @@
 # Updating your Packages and Dynamo Libraries for Dynamo 3.x and NET8
 
+{% hint style="info" %}
+**Applies to**: Dynamo 3.x (3.0 - 3.6)  
+**Target Runtime**: .NET 8  
+**Key Changes**: Runtime migration from .NET 4.8, Python engine updates
+
+For other versions, see: [Dynamo 2.x Migration](6-0-updating-your-packages-and-dynamo-libraries-for-dynamo-2x.md) | [Dynamo 4.x Migration](6-2-updating-your-packages-and-dynamo-libraries-for-dynamo-4x.md)
+{% endhint %}
+
 ### Introduction <a href="#introduction" id="introduction"></a>
 
 This section contains information on issues you may encounter while migrating your graphs, packages, and libraries to Dynamo 3.x.

diff --git a/...ing_for_dynamo/6-2-updating-your-packages-and-dynamo-libraries-for-dynamo-4x.md b/...ing_for_dynamo/6-2-updating-your-packages-and-dynamo-libraries-for-dynamo-4x.md
@@ -1,5 +1,13 @@
 # Updating your Packages and Dynamo Libraries for Dynamo 4.x
 
+{% hint style="info" %}
+**Applies to**: Dynamo 4.x (4.0+)  
+**Target Runtime**: .NET 10  
+**Key Changes**: PythonNet3 default, .NET 10 migration, obsolete API removal, significant performance improvements
+
+For other versions, see: [Dynamo 2.x Migration](6-0-updating-your-packages-and-dynamo-libraries-for-dynamo-2x.md) | [Dynamo 3.x Migration](6-1-updating-your-packages-and-dynamo-libraries-for-dynamo-3x-Net8.md)
+{% endhint %}
+
 ### Introduction <a href="#introduction" id="introduction"></a>
 
 This section contains information on issues you may encounter while migrating your graphs, packages and libraries to Dynamo 4.x.

diff --git a/11_developer_primer/3_developing_for_dynamo/README.md b/11_developer_primer/3_developing_for_dynamo/README.md
@@ -1,5 +1,14 @@
 # Developing for Dynamo
 
+{% hint style="warning" %}
+**Important for Package Developers**: API compatibility varies significantly across Dynamo versions. See version-specific migration guides:
+- [Dynamo 2.x Migration](6-0-updating-your-packages-and-dynamo-libraries-for-dynamo-2x.md)
+- [Dynamo 3.x Migration](6-1-updating-your-packages-and-dynamo-libraries-for-dynamo-3x-Net8.md)
+- [Dynamo 4.x Migration](6-2-updating-your-packages-and-dynamo-libraries-for-dynamo-4x.md)
+
+For general version guidance, see the [Version Guide](../../VERSION_GUIDE.md).
+{% endhint %}
+
 Regardless of experience level, the Dynamo platform is designed for all users to be contributors. There are several development options that target different abilities and skill levels, each with its strengths and weaknesses depending on the goal. Below we will outline the different options and how to choose one over another.
 
 ![Three development environments](../../.gitbook/assets/developing-for-dynamo.png)

diff --git a/1_introduction/README.md b/1_introduction/README.md
@@ -1,5 +1,9 @@
 # Introduction
 
+{% hint style="success" %}
+**Welcome!** This Primer covers Dynamo versions 2.13 through 4.0+. Most core concepts apply across all versions. When content is version-specific, we'll clearly indicate which version(s) it applies to. See the [Version Guide](../VERSION_GUIDE.md) for details.
+{% endhint %}
+
 From its origins as an add-on for Building Information Modeling in Revit, Dynamo has matured to become many things. Above all else it is a platform, enabling designers to explore visual programming, solve problems, and make their own tools. Let's start our journey with Dynamo by setting some context - what is it and how do I approach using it?
 
 ![Dynamo Ecosystem](<../.gitbook/assets/intro dynamo cover.jpg>)
diff --git a/2_setup_for_dynamo/README.md b/2_setup_for_dynamo/README.md
@@ -1,5 +1,9 @@
 # Setup for Dynamo
 
+{% hint style="info" %}
+**Version Compatibility**: This guide applies to all Dynamo versions (2.13+). For version-specific installation notes, see the [Version Guide](../VERSION_GUIDE.md).
+{% endhint %}
+
 ### Dynamo as Extension vs Dynamo Sandbox
 
 Dynamo is an active open-source development project. Find out the [list of software that supports Dynamo](http://dynamobim.org/download/).

diff --git a/6_custom_nodes_and_packages/6-2_packages/1-introduction.md b/6_custom_nodes_and_packages/6-2_packages/1-introduction.md
@@ -1,5 +1,10 @@
 # Package Introduction
 
+{% hint style="warning" %}
+**Package Compatibility**: Packages built for different Dynamo versions may not be compatible across all versions due to runtime changes (.NET 4.8 → .NET 8 → .NET 10). When installing packages, check for version-specific builds. See [Version Guide](../../VERSION_GUIDE.md) for details on package compatibility across versions.
+{% endhint %}
+
+
 Dynamo offers a vast number of features out of the box and also maintains an extensive package library that can significantly extend Dynamo’s capability. A package is a collection of custom nodes or additional functionality. The Dynamo Package Manager is a portal for the community to download any package that has been published online. These toolsets are developed by third parties to extend Dynamo's core functionality, accessible to all, and ready to download at the click of the button.
 
 ![Package Manager Site](../../.gitbook/assets/dpm.jpg)

diff --git a/7_dynamo_for_revit/README.md b/7_dynamo_for_revit/README.md
@@ -1,5 +1,10 @@
 # Dynamo for Revit
 
+{% hint style="info" %}
+**Revit Integration**: Dynamo is bundled with Revit 2020 and later. The version of Dynamo bundled with Revit depends on your Revit version. See the [Version Guide](../VERSION_GUIDE.md) and [Host Integration Map](../a_appendix/host-integration-map.md) for compatibility details.
+{% endhint %}
+
+
 While Dynamo is a flexible environment, designed to port into a wide range of programs, it was originally created for use with Revit. A visual program creates robust options for a Building Information Model (BIM). Dynamo offers a whole suite of nodes specifically designed for Revit, as well as third-party libraries from a thriving AEC community. This chapter focuses on the basics of using Dynamo in Revit.
 
 ![](<../.gitbook/assets/Dynamo for Revit-01.jpg>)
diff --git a/8_coding_in_dynamo/8-3_python/README.md b/8_coding_in_dynamo/8-3_python/README.md
@@ -1,5 +1,13 @@
 # Python
 
+{% hint style="warning" %}
+**Python Engine Versions**: Python support varies across Dynamo versions:
+- **Dynamo 2.x - 3.x**: IronPython2 default (CPython/PythonNet3 available as engines)
+- **Dynamo 4.x+**: PythonNet3 default for new nodes (backward compatible with IronPython2)
+
+For migration guidance, see [Updating for Dynamo 4.x](../../11_developer_primer/3_developing_for_dynamo/6-2-updating-your-packages-and-dynamo-libraries-for-dynamo-4x.md)
+{% endhint %}
+
 Python is a widely-used programming language whose popularity has a lot to do with its style of syntax. It's highly readable, which makes it easier to learn than many other languages. Python supports modules and packages and can be embedded into existing applications. For information about how to get up and running with Python, a good resource is the ["Getting Started"](https://www.python.org/about/gettingstarted/) page on [Python.org](https://www.python.org)
 
 ![](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FY5ZuHF3yuXFWp1C46ZSo%2Fuploads%2Fgit-blob-6bd72c745aa81df1f25c09989fa19f672c631e59%2Fpythonlogo.jpg?alt=media)
diff --git a/8_coding_in_dynamo/8-4_language-changes/1-dynamo-2.0-language-changes.md b/8_coding_in_dynamo/8-4_language-changes/1-dynamo-2.0-language-changes.md
@@ -1,5 +1,9 @@
 # Language Changes
 
+{% hint style="info" %}
+**Version-Specific Content**: This page documents language changes introduced in Dynamo 2.0. These changes apply to all subsequent versions (2.x, 3.x, 4.x) unless otherwise noted.
+{% endhint %}
+
 The language changes section provides an overview of the updates and modifications made to the language in Dynamo in each version. These changes can impact functionality, performance, and usage, and this guide will help users understand when and why to adapt to these updates.
 
 ## Dynamo 2.0 Language Changes

diff --git a/CONTRIBUTING_VERSION_GUIDE.md b/CONTRIBUTING_VERSION_GUIDE.md
@@ -0,0 +1,155 @@
+# Contributing to Multi-Version Documentation
+
+## Purpose
+This document provides guidelines for contributors to maintain version-specific content in the Dynamo Primer across multiple Dynamo versions (2.13+).
+
+## Our Approach
+The Dynamo Primer uses a **unified documentation approach** with **inline version indicators**. We avoid maintaining separate documentation trees for each version, instead marking version-specific content where it appears.
+
+## When to Add Version Indicators
+
+### Always Mark These Scenarios:
+1. **Breaking Changes**: API changes, removed features, syntax changes
+2. **New Features**: Features available only in certain versions
+3. **Runtime Changes**: .NET Framework version differences (.NET 4.8 → .NET 8 → .NET 10)
+4. **Package Compatibility**: Changes affecting third-party packages
+5. **Python Engine Changes**: IronPython2 vs PythonNet3
+
+### Examples of Version-Specific Content:
+- Package migration guides (e.g., updating from 2.x to 3.x)
+- Python engine selection (IronPython2 vs PythonNet3 in Dynamo 4.x)
+- .NET runtime requirements for developers
+- Host application integration changes
+
+## How to Mark Version-Specific Content
+
+### Use GitBook Hint Boxes
+GitBook provides native hint syntax that renders as colored callout boxes:
+
+#### For General Information
+```markdown
+{% hint style="info" %}
+**Version Note**: This feature is available in Dynamo 3.0 and later.
+{% endhint %}
+```
+
+#### For Important Warnings
+```markdown
+{% hint style="warning" %}
+**Compatibility**: This syntax changed in Dynamo 2.0. For older versions, use the legacy syntax.
+{% endhint %}
+```
+
+#### For Positive Messages
+```markdown
+{% hint style="success" %}
+**New Feature**: Dynamo 4.0 introduces significant performance improvements!
+{% endhint %}
+```
+
+#### For Critical Alerts
+```markdown
+{% hint style="danger" %}
+**Breaking Change**: This API was removed in Dynamo 4.0. Use the replacement API instead.
+{% endhint %}
+```
+
+### Placement Guidelines
+1. **Page Level**: Add hints near the top of pages that are entirely version-specific
+2. **Section Level**: Add hints before sections describing version-specific features
+3. **Inline**: Use bold text for brief inline version notes: `**Dynamo 3.0+:**`
+
+### Version Reference Format
+Use these formats consistently:
+- **Single version**: "Dynamo 2.13", "Dynamo 3.0"
+- **Version range**: "Dynamo 2.x (2.13-2.19)", "Dynamo 3.0+"
+- **Multiple versions**: "Dynamo 2.x and 3.x"
+
+## Version Guide Maintenance
+
+### Updating VERSION_GUIDE.md
+When a new Dynamo version is released:
+
+1. Update the version table with the new version
+2. Add any major changes to the "Major Version Differences" section
+3. Update the "Host Application Integration" table if needed
+4. Link to new migration guides if created
+
+### Creating Migration Guides
+For major version changes, create a new migration guide following the pattern:
+- `6-X-updating-your-packages-and-dynamo-libraries-for-dynamo-Xx.md`
+- Include: runtime changes, API changes, migration steps, known issues
+- Add a version badge at the top linking to other version guides
+
+## Best Practices
+
+### DO:
+✅ Link to the VERSION_GUIDE.md for comprehensive version information  
+✅ Test instructions across multiple versions when possible  
+✅ Use consistent version notation  
+✅ Update version tables when versions change  
+✅ Mark breaking changes clearly  
+
+### DON'T:
+❌ Duplicate version information across multiple pages  
+❌ Use vague version references like "recent versions" or "older versions"  
+❌ Remove content for older versions unless truly obsolete  
+❌ Add version notes to core concepts that apply across all versions  
+❌ Create separate documentation trees per version  
+
+## Testing Your Changes
+
+Before submitting a PR with version-specific content:
+
+1. **Clarity Check**: Is it immediately clear which version(s) this applies to?
+2. **Context Check**: Does the reader have enough context to understand the difference?
+3. **Link Check**: Are related version guides properly linked?
+4. **Consistency Check**: Does the formatting match other version indicators?
+
+## Examples from the Primer
+
+### Good Example 1: Page-Level Version Context
+```markdown
+# Updating your Packages and Dynamo Libraries for Dynamo 4.x
+
+{% hint style="info" %}
+**Applies to**: Dynamo 4.x (4.0+)  
+**Target Runtime**: .NET 10  
+**Key Changes**: PythonNet3 default, obsolete API removal
+
+For other versions, see: [Dynamo 2.x](link) | [Dynamo 3.x](link)
+{% endhint %}
+```
+
+### Good Example 2: Section-Level Warning
+```markdown
+### Installing Packages
+
+{% hint style="warning" %}
+**Package Compatibility**: Packages built for different Dynamo versions may not be 
+compatible due to runtime changes. Check for version-specific builds.
+{% endhint %}
+```
+
+### Good Example 3: Inline Version Note
+```markdown
+The Python engine defaults to IronPython2 in Dynamo 2.x and 3.x, but **Dynamo 4.0+** 
+uses PythonNet3 for all new Python nodes.
+```
+
+## Questions?
+If you're unsure whether to add version indicators, ask yourself:
+- "Will this work the same way in all supported Dynamo versions?"
+- "Could a user from a different version be confused by this?"
+- "Is there a breaking change or new feature here?"
+
+If the answer is "no" to the first question or "yes" to the others, add a version indicator.
+
+## Resources
+- Main version guide: [VERSION_GUIDE.md](VERSION_GUIDE.md)
+- Migration guides: See `11_developer_primer/3_developing_for_dynamo/6-*` files
+- GitBook hint syntax: https://docs.gitbook.com/content-editor/blocks/hint
+
+---
+Last updated: 2026-01-26  
+Maintainers: See [CONTRIBUTING.md] for general contribution guidelines