docs: Add plotly.js v4 migration guide

_data/display_as.yml

@@ -13,6 +13,9 @@ signal-analysis:
 file_settings:
     reference: '#fundamentals'
     text: Fundamentals
+guide:
+    reference: '#guides'
+    text: Guides
 basic:
     reference: '#basic-charts'
     text: Basic

_data/display_as_py_r_js.yml

@@ -13,6 +13,9 @@ signal-analysis:
 file_settings:
     reference: 'plotly-fundamentals'
     text: Fundamentals
+guide:
+    reference: 'guides'
+    text: Guides
 basic:
     reference: 'basic-charts'
     text: Basic Charts

_includes/layouts/side-bar.html

@@ -157,6 +157,9 @@
                         <a href="/javascript/configuration-options/" class="js-splash--navigation-item">Configuration
                             Options</a>
                     </li>
+                    <li class="--sidebar-item">
+                        <a href="/javascript/guides/" class="js-splash--navigation-item">Guides</a>
+                    </li>
                     {% endif %}
 
                     <!-- R Specific -->

_includes/posts/documentation_eg.html

@@ -8,6 +8,8 @@
 {%- for page in languagelist -%}
 {% if page.display_as == "file_settings" %}
 {% assign file_settings = true %}
+{% elsif page.display_as == "guide" %}
+{% assign guide = true %}
 {% elsif page.display_as == "chart_type" or page.display_as == "basic" %}
 {% assign chart_type = true %}
 {% elsif page.display_as == "statistical" %}
@@ -115,6 +117,30 @@
 </section>
 {% endif %}
 
+{% if guide %}
+<section class="--tutorial-section">
+    <header class="--section-header">
+
+        {% if show_header %}
+        <a href="#guides" name="guides" id="guides">Guides</a>
+        {% endif %}
+
+    </header>
+    <section class="--grid">
+        <ul class="--grid-list">
+            {%- for page in languagelist -%}
+            {% if page.display_as == "guide" %}
+
+            {% include layouts/grid-item.html %}
+
+
+            {% endif %}
+            {%- endfor -%}
+        </ul>
+    </section>
+</section>
+{% endif %}
+
 {% if ai_ml %}
 <section class="--tutorial-section" id="ai_ml">
     <header class="--section-header">

_includes/posts/mainlang_documentation_eg.html

@@ -11,6 +11,8 @@
     {% if page.layout != "langindex" %}
         {% if page.display_as == "file_settings" %}
             {% assign file_settings = true %}
+        {% elsif page.display_as == "guide" %}
+            {% assign guide = true %}
         {% elsif page.display_as == "chart_type" or page.display_as == "basic" %}
             {% assign chart_type = true %}
         {% elsif page.display_as == "statistical" %}
@@ -88,6 +90,39 @@
 </section>
 {% endif %}
 
+{% if guide %}
+<section class="--tutorial-section">
+    <header class="--section-header">
+        <a href="#guides" name="guides" id="guides">Guides</a>
+
+        {% assign forloop_idx = 0 %}
+        {%- for page in languagelist -%}
+            {% if page.display_as == "guide" and page.layout != "langindex" %}
+                {% assign forloop_idx = forloop_idx | plus:1 %}
+            {% endif %}
+        {%- endfor -%}
+
+        {% if forloop_idx >= num_examples %}
+        <a href="/{{language}}/guides" class="langindexlink">More Guides &raquo;</a>
+        {% endif %}
+    </header>
+    <section class="--grid">
+        <ul class="--grid-list">
+
+            {% assign forloop_idx = 0 %}
+
+            {%- for page in languagelist -%}
+                {% if page.display_as == "guide" and page.layout != "langindex" and forloop_idx < num_examples  %}
+                    {% assign forloop_idx = forloop_idx | plus:1 %}
+                    {% include layouts/grid-item.html %}
+                {% endif %}
+            {%- endfor -%}
+
+        </ul>
+    </section>
+</section>
+{% endif %}
+
 
 
 

_posts/plotly_js/guides/2026-07-17-plotly_js-guides-index.html

@@ -0,0 +1,25 @@
+---
+permalink: javascript/guides/
+description: Guides for Plotly.js, including migration guides between major versions with breaking changes and before/after examples.
+name: Guides
+layout: langindex
+display_as: guide
+language: plotly_js
+thumbnail: thumbnail/mixed.jpg
+---
+
+
+<header class="--welcome">
+  <div class="--welcome-body">
+    <div class="--title">
+      <div class="--body">
+        <h1>Plotly.js Guides</h1>
+        <p>{{page.description}}</p>
+        {% include layouts/dashplug.html %}
+      </div>
+    </div>
+  </div>
+</header>
+
+    {% assign languagelist = site.posts | where:"language","plotly_js" | where:"display_as","guide" | where: "layout","base" | sort: "order" %}
+        {% include posts/documentation_eg.html %}

_posts/plotly_js/fundamentals/plotly-js-3-changes/2024-10-09-plotly-js-3-changes.md → _posts/plotly_js/guides/migrating-to-v3/2024-10-09-migrating-to-v3.md

@@ -1,13 +1,16 @@
 ---
 description: Learn about the changes in Plotly.js version 3.
-display_as: file_settings
+display_as: guide
 language: plotly_js
 layout: base
-name: Version 3 Changes
-order: 27
+name: Migrating to Plotly.js v3
+order: 3
 page_type: u-guide
-permalink: javascript/version-3-changes/
-redirect_from: javascript/pointcloud/
+permalink: javascript/guides/migrating-to-v3/
+redirect_from:
+- javascript/pointcloud/
+- javascript/version-3-changes/
+- javascript/migrating-to-v3/
 sitemap: false
 thumbnail: thumbnail/pointcloud.jpg
 ---
@@ -359,4 +362,4 @@ var data = [{
     cmin: 0,
     cmax: 100
 }];
-```
+```