activeadmin · tagliala · Mar 20, 2026 · Copilot · Mar 20, 2026 · tagliala
diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -1,4 +1,3 @@
-import { version } from '../../package.json'
 import { defineConfig } from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
@@ -17,7 +16,7 @@ export default defineConfig({
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     nav: [
-      { text: 'Guide', link: '/0-installation' },
+      { text: 'Guide', link: '/v3/0-installation' },
       { text: 'Discuss', link: 'https://github.com/activeadmin/activeadmin/discussions' },
       {
         text: 'Demo',
@@ -27,8 +26,12 @@ export default defineConfig({
         ]
       },
       {
-        text: version.replace("-", "."), // use Ruby format for version text
+        text: 'v3.x', // use Ruby format for version text
         items: [
+          {
+            text: 'v3.x',
+            link: '/v3/0-installation'
+          },
           {
             text: 'Changelog',
             link: 'https://github.com/activeadmin/activeadmin/releases',
@@ -40,40 +43,6 @@ export default defineConfig({
         ],
       }
     ],
-    sidebar: [
-      {
-        text: 'Setup',
-        items: [
-          { text: 'Installation', link: '/0-installation' },
-          { text: 'Configuration', link: '/1-general-configuration' }
-        ]
-      },
-      {
-        text: 'Resources',
-        items: [
-          { text: 'Working with Resources', link: '/2-resource-customization' },
-          { text: 'Customize the Index page', link: '/3-index-pages' },
-          { text: 'Index as a Table', link: '/3-index-pages/index-as-table' },
-          { text: 'Custom Index View', link: '/3-index-pages/custom-index' },
-          { text: 'CSV Format', link: '/4-csv-format' },
-          { text: 'Forms', link: '/5-forms' },
-          { text: 'Customize the Show Page', link: '/6-show-pages' },
-          { text: 'Sidebar Sections', link: '/7-sidebars' },
-          { text: 'Custom Controller Actions', link: '/8-custom-actions' },
-          { text: 'Batch Actions', link: '/9-batch-actions' },
-          { text: 'Decorators', link: '/11-decorators' },
-          { text: 'Authorization Adapter', link: '/13-authorization-adapter' }
-        ]
-      },
-      {
-        text: 'Other',
-        items: [
-          { text: 'Custom Pages', link: '/10-custom-pages' },
-          { text: 'Arbre Components', link: '/12-arbre-components' },
-          { text: 'Gotchas', link: '/14-gotchas' },
-        ]
-      }
-    ],
     socialLinks: [
       { icon: 'github', link: 'https://github.com/activeadmin/activeadmin' },
       { icon: 'slack', link: 'https://activeadmin.slack.com/' },

diff --git a/docs/CNAME b/docs/CNAME
diff --git a/docs/index.md b/docs/index.md
@@ -10,7 +10,7 @@ hero:
   actions:
     - theme: brand
       text: Getting Started
-      link: /0-installation
+      link: /v3/0-installation
     - theme: alt
       text: View on GitHub
       link: https://github.com/activeadmin/activeadmin
@@ -25,12 +25,12 @@ features:
   - icon: 🎬
     title: Action Items
     details: Add buttons or links as action items in the page header for a resource.
-    link: /8-custom-actions
+    link: /v3/8-custom-actions
     linkText: Learn about action items
   - icon: 🔍
     title: Filters
     details: Allow users to filter resources by searching strings, text fields, dates, and numeric values.
-    link: /3-index-pages
+    link: /v3/3-index-pages
     linkText: Learn about filters
   - icon: 🗂️
     title: Scopes
@@ -41,7 +41,7 @@ features:
   - icon: 📋
     title: Sidebar Sections
     details: Add your own sections to the sidebar using a simple DSL.
-    link: /7-sidebars
+    link: /v3/7-sidebars
     linkText: Learn about sidebar sections
   - icon: 💾
     title: Downloads

diff --git a/docs/0-installation.md → docs/v3/0-installation.md b/docs/0-installation.md → docs/v3/0-installation.md
diff --git a/docs/1-general-configuration.md → docs/v3/1-general-configuration.md b/docs/1-general-configuration.md → docs/v3/1-general-configuration.md
diff --git a/docs/10-custom-pages.md → docs/v3/10-custom-pages.md b/docs/10-custom-pages.md → docs/v3/10-custom-pages.md
diff --git a/docs/11-decorators.md → docs/v3/11-decorators.md b/docs/11-decorators.md → docs/v3/11-decorators.md
diff --git a/docs/12-arbre-components.md → docs/v3/12-arbre-components.md b/docs/12-arbre-components.md → docs/v3/12-arbre-components.md
diff --git a/docs/13-authorization-adapter.md → docs/v3/13-authorization-adapter.md b/docs/13-authorization-adapter.md → docs/v3/13-authorization-adapter.md
diff --git a/docs/14-gotchas.md → docs/v3/14-gotchas.md b/docs/14-gotchas.md → docs/v3/14-gotchas.md
diff --git a/docs/2-resource-customization.md → docs/v3/2-resource-customization.md b/docs/2-resource-customization.md → docs/v3/2-resource-customization.md
diff --git a/docs/3-index-pages.md → docs/v3/3-index-pages.md b/docs/3-index-pages.md → docs/v3/3-index-pages.md
diff --git a/docs/3-index-pages/custom-index.md → docs/v3/3-index-pages/custom-index.md b/docs/3-index-pages/custom-index.md → docs/v3/3-index-pages/custom-index.md
diff --git a/docs/3-index-pages/index-as-block.md → docs/v3/3-index-pages/index-as-block.md b/docs/3-index-pages/index-as-block.md → docs/v3/3-index-pages/index-as-block.md
diff --git a/docs/3-index-pages/index-as-blog.md → docs/v3/3-index-pages/index-as-blog.md b/docs/3-index-pages/index-as-blog.md → docs/v3/3-index-pages/index-as-blog.md
diff --git a/docs/3-index-pages/index-as-grid.md → docs/v3/3-index-pages/index-as-grid.md b/docs/3-index-pages/index-as-grid.md → docs/v3/3-index-pages/index-as-grid.md
diff --git a/docs/3-index-pages/index-as-table.md → docs/v3/3-index-pages/index-as-table.md b/docs/3-index-pages/index-as-table.md → docs/v3/3-index-pages/index-as-table.md
diff --git a/docs/4-csv-format.md → docs/v3/4-csv-format.md b/docs/4-csv-format.md → docs/v3/4-csv-format.md
diff --git a/docs/5-forms.md → docs/v3/5-forms.md b/docs/5-forms.md → docs/v3/5-forms.md
diff --git a/docs/6-show-pages.md → docs/v3/6-show-pages.md b/docs/6-show-pages.md → docs/v3/6-show-pages.md
diff --git a/docs/7-sidebars.md → docs/v3/7-sidebars.md b/docs/7-sidebars.md → docs/v3/7-sidebars.md
diff --git a/docs/8-custom-actions.md → docs/v3/8-custom-actions.md b/docs/8-custom-actions.md → docs/v3/8-custom-actions.md
diff --git a/docs/9-batch-actions.md → docs/v3/9-batch-actions.md b/docs/9-batch-actions.md → docs/v3/9-batch-actions.md
diff --git a/docs/v3/config.js b/docs/v3/config.js
@@ -0,0 +1,63 @@
+import { defineAdditionalConfig } from 'vitepress'
+
+export default defineAdditionalConfig({
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/v3/0-installation' },
+      { text: 'Discuss', link: 'https://github.com/activeadmin/activeadmin/discussions' },
+      {
+        text: 'Demo',
+        items: [
+          { text: 'GitHub Repository', link: 'https://github.com/activeadmin/demo.activeadmin.info' },
+          { text: 'Demo App', link: 'https://demo.activeadmin.info/' },
+        ],
+      },
+      {
+        text: 'v3.x',
+        items: [
+          { text: 'v3.x', link: '/v3/0-installation' },
+          { text: 'Changelog', link: 'https://github.com/activeadmin/activeadmin/releases' },
+          { text: 'Contributing', link: 'https://github.com/activeadmin/activeadmin/blob/master/CONTRIBUTING.md' },
+        ],
+      },
+    ],
+    sidebar: [
+      {
+        text: 'Setup',
+        items: [
+          { text: 'Installation', link: '/v3/0-installation' },
+          { text: 'Configuration', link: '/v3/1-general-configuration' },
+        ],
+      },
+      {
+        text: 'Resources',
+        items: [
+          { text: 'Working with Resources', link: '/v3/2-resource-customization' },
+          { text: 'Customize the Index page', link: '/v3/3-index-pages' },
+          { text: 'Index as a Table', link: '/v3/3-index-pages/index-as-table' },
+          { text: 'Custom Index View', link: '/v3/3-index-pages/custom-index' },
+          { text: 'CSV Format', link: '/v3/4-csv-format' },
+          { text: 'Forms', link: '/v3/5-forms' },
+          { text: 'Customize the Show Page', link: '/v3/6-show-pages' },
+          { text: 'Sidebar Sections', link: '/v3/7-sidebars' },
+          { text: 'Custom Controller Actions', link: '/v3/8-custom-actions' },
+          { text: 'Batch Actions', link: '/v3/9-batch-actions' },
+          { text: 'Decorators', link: '/v3/11-decorators' },
+          { text: 'Authorization Adapter', link: '/v3/13-authorization-adapter' },
+        ],
+      },
+      {
+        text: 'Other',
+        items: [
+          { text: 'Custom Pages', link: '/v3/10-custom-pages' },
+          { text: 'Arbre Components', link: '/v3/12-arbre-components' },
+          { text: 'Gotchas', link: '/v3/14-gotchas' },
+        ],
+      },
+    ],
+    editLink: {
+      pattern: 'https://github.com/activeadmin/activeadmin/edit/master/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+  },
+})
diff --git a/docs/documentation.md → docs/v3/documentation.md b/docs/documentation.md → docs/v3/documentation.md
diff --git a/docs/v3/index.md b/docs/v3/index.md
@@ -0,0 +1,49 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: ActiveAdmin
+  text: An admin engine for Rails applications
+  tagline: Abstracts common patterns to implement beautiful and elegant interfaces with ease.
+
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /v3/0-installation
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/activeadmin/activeadmin
+
+features:
+  - icon: 🌎
+    title: Global Navigation
+    details: Customizable navigation allows you to create usable admin interfaces for your business.
+  - icon: 🔒
+    title: User Authentication
+    details: Use the bundled Devise configuration or implement your own authorization using the provided hooks.
+  - icon: 🎬
+    title: Action Items
+    details: Add buttons or links as action items in the page header for a resource.
+    link: /v3/8-custom-actions
+    linkText: Learn about action items
+  - icon: 🔍
+    title: Filters
+    details: Allow users to filter resources by searching strings, text fields, dates, and numeric values.
+    link: /v3/3-index-pages
+    linkText: Learn about filters
+  - icon: 🗂️
+    title: Scopes
+    details: Use scopes to create sections of mutually exclusive resources for quick navigation and reporting.
+  - icon: 📑
+    title: Custom Index Views
+    details: The default index screen is a table view, but custom index views are supported.
+  - icon: 📋
+    title: Sidebar Sections
+    details: Add your own sections to the sidebar using a simple DSL.
+    link: /v3/7-sidebars
+    linkText: Learn about sidebar sections
+  - icon: 💾
+    title: Downloads
+    details: Each resource becomes available as CSV, JSON, and XML with customizable output.
+---
diff --git a/eslint.config.js b/eslint.config.js
@@ -6,6 +6,7 @@ export default [
     ignores: [
       "app/assets/**",
       "coverage/**",
+      "docs/.vitepress/cache/**",
       "docs/.vitepress/dist/**",
       "lib/generators/**",
       "src/**",

diff --git a/package.json b/package.json
@@ -31,7 +31,7 @@
     "gherkin-lint": "^4.2.4",
     "rollup": "^4.60.0",
     "tailwindcss": "^4.2.2",
-    "vitepress": "^1.6.4"
+    "vitepress": "^2.0.0-alpha.17"
   },
   "scripts": {
     "gherkin-lint": "gherkin-lint",