chore(docs): rename default docs plugin to user_docs for consistent versioned dir naming

Background: of the four versioned docs sections, three (admin_docs,
developer_docs, components) use the standard Docusaurus
`<plugin_id>_versioned_docs` / `<plugin_id>_versioned_sidebars` /
`<plugin_id>_versions.json` naming on disk. The fourth — the
user-docs section — was wired through preset-classic's bundled docs
slot, which uses the special "default" plugin id that gets no prefix
(`versioned_docs/`, `versioned_sidebars/`, `versions.json`). This is
a Docusaurus quirk, not a Superset choice, but the result is
inconsistent top-level layout and a confusingly-bare `versioned_docs`
that looks like a global rather than a per-section dir.

Fix: configure user-docs as an explicit `plugin-content-docs`
instance with `id: 'user_docs'` instead of relying on
preset-classic's default docs slot. Now all four sections produce
parallel-named files at the docs/ root.

Changes:
- docusaurus.config.ts: add user_docs to dynamicPlugins; set
  `docs: false` on preset-classic.
- versions-config.json: rename `docs` key → `user_docs`.
- File renames (preserves git history via `git mv`):
    versioned_docs/        → user_docs_versioned_docs/
    versioned_sidebars/    → user_docs_versioned_sidebars/
    versions.json          → user_docs_versions.json
- src/theme/DocVersionBadge/index.js: update PLUGIN_ID_TO_BASE_PATH
  (`default` → `user_docs`) and refresh the comment.
- scripts/manage-versions.mjs: drop every `section === 'docs'`
  special case; the user_docs section's source dir is still `docs/`
  (we didn't rename the content folder), but everything else is
  uniform with the other three sections — net code reduction.
- package.json: rename `version:add:docs` → `version:add:user_docs`
  and `version:remove:docs` → `version:remove:user_docs` script
  aliases. CLI breaking change for anyone scripting against these,
  but this is internal docs tooling and the new name matches the
  on-disk naming.
- README.md, DOCS_CLAUDE.md: update examples and naming notes.

URL impact: none. The user-docs URL prefix is governed by
`routeBasePath: 'user-docs'` (unchanged), not by the plugin id. The
existing 6.0.0 versioned URL `/user-docs/6.0.0/...` continues to
resolve, verified via local `yarn build`.

What this enables: when the next 6.1.0 cut runs (in a follow-up PR
on top of this), the snapshot will land at
`user_docs_versioned_docs/version-6.1.0/` instead of
`versioned_docs/version-6.1.0/`, and the top-level docs/ directory
will list its versioning artifacts in four parallel sets — much
easier to scan during review.

docs/DOCS_CLAUDE.md

@@ -52,11 +52,11 @@ yarn serve                # Serve built site locally
 # For maximum-detail databases.json, drop the `database-diagnostics`
 # artifact from Python-Integration CI at src/data/databases.json before
 # cutting. See README.md "Before You Cut".
-yarn version:add:docs <version>              # Add new docs version
+yarn version:add:user_docs <version>              # Add new docs version
 yarn version:add:admin_docs <version>        # Add admin docs version
 yarn version:add:developer_docs <version>    # Add developer docs version
 yarn version:add:components <version>        # Add components version
-yarn version:remove:docs <version>           # Remove docs version
+yarn version:remove:user_docs <version>           # Remove docs version
 yarn version:remove:admin_docs <version>     # Remove admin docs version
 yarn version:remove:developer_docs <version> # Remove developer docs version
 yarn version:remove:components <version>     # Remove components version
@@ -228,17 +228,20 @@ Versions are managed through `versions-config.json`:
 
 ```bash
 # ✅ CORRECT - Updates both Docusaurus and versions-config.json
-yarn version:add:docs 6.1.0
+yarn version:add:user_docs 6.1.0
 
 # ❌ WRONG - Only updates Docusaurus, breaks version dropdown
 yarn docusaurus docs:version 6.1.0
 ```
 
 ### Version Files Created
-When versioning, these files are created:
-- `versioned_docs/version-X.X.X/` - Snapshot of current docs
-- `versioned_sidebars/version-X.X.X-sidebars.json` - Sidebar config
-- `versions.json` - List of all versions
+When versioning, these files are created (per section, with the
+section's plugin id as prefix):
+- `<section>_versioned_docs/version-X.X.X/` - Snapshot of current docs
+- `<section>_versioned_sidebars/version-X.X.X-sidebars.json` - Sidebar config
+- `<section>_versions.json` - List of all versions
+
+Section plugin ids: `user_docs`, `admin_docs`, `developer_docs`, `components`.
 
 ## 🎨 Styling and Theming
 
@@ -386,7 +389,7 @@ Docusaurus includes Algolia DocSearch integration configured in `docusaurus.conf
 
 ## 🚫 Common Pitfalls to Avoid
 
-1. **Never use `yarn docusaurus docs:version`** - Use `yarn version:add:docs` instead
+1. **Never use `yarn docusaurus docs:version`** - Use `yarn version:add:user_docs` instead
 2. **Don't edit versioned docs directly** - Edit current docs and create new version
 3. **Avoid absolute paths in links** - Use relative paths for maintainability
 4. **Don't forget frontmatter** - Every doc needs title and description
@@ -416,7 +419,7 @@ yarn eslint
 ### Version Issues
 If versions don't appear in dropdown:
 1. Check `versions-config.json` includes the version
-2. Verify version files exist in `versioned_docs/`
+2. Verify version files exist in `<section>_versioned_docs/`
 3. Restart dev server
 
 ## 📚 Resources

docs/README.md

@@ -53,7 +53,7 @@ Also: confirm `master` CI is green, and that your local checkout matches the SHA
 
 ```bash
 # Main Documentation
-yarn version:add:docs 1.2.0
+yarn version:add:user_docs 1.2.0
 
 # Admin Docs
 yarn version:add:admin_docs 1.2.0
@@ -98,7 +98,7 @@ If creating versions manually, you'll need to:
    - **Versioned sidebars**: `[section]_versioned_sidebars/version-X.X.X-sidebars.json`
    - **Versions list**: `[section]_versions.json`
 
-   Note: For main docs, the prefix is omitted (e.g., `versioned_docs/` instead of `docs_versioned_docs/`)
+   All four sections (`user_docs`, `admin_docs`, `developer_docs`, `components`) follow this naming pattern uniformly.
 
 3. **Important**: After adding a version, restart the development server to see changes:
    ```bash
@@ -111,7 +111,7 @@ If creating versions manually, you'll need to:
 #### Using Automated Scripts (Recommended)
 ```bash
 # Main Documentation
-yarn version:remove:docs 1.0.0
+yarn version:remove:user_docs 1.0.0
 
 # Admin Docs
 yarn version:remove:admin_docs 1.0.0
@@ -127,19 +127,19 @@ yarn version:remove:components 1.0.0
 To manually remove a version:
 
 1. **Delete the version folder** from the appropriate location:
-   - Main docs: `versioned_docs/version-X.X.X/` (no prefix for main)
+   - User Docs: `user_docs_versioned_docs/version-X.X.X/`
    - Admin Docs: `admin_docs_versioned_docs/version-X.X.X/`
    - Developer Docs: `developer_docs_versioned_docs/version-X.X.X/`
    - Components: `components_versioned_docs/version-X.X.X/`
 
 2. **Delete the version metadata file**:
-   - Main docs: `versioned_sidebars/version-X.X.X-sidebars.json` (no prefix)
+   - User Docs: `user_docs_versioned_sidebars/version-X.X.X-sidebars.json`
    - Admin Docs: `admin_docs_versioned_sidebars/version-X.X.X-sidebars.json`
    - Developer Docs: `developer_docs_versioned_sidebars/version-X.X.X-sidebars.json`
    - Components: `components_versioned_sidebars/version-X.X.X-sidebars.json`
 
 3. **Update the versions list file**:
-   - Main docs: `versions.json`
+   - User Docs: `user_docs_versions.json`
    - Admin Docs: `admin_docs_versions.json`
    - Developer Docs: `developer_docs_versions.json`
    - Components: `components_versions.json`
@@ -212,8 +212,8 @@ docs: {
 If you accidentally used `yarn docusaurus docs:version` instead of `yarn version:add`:
 1. **Problem**: The version files were created but `versions-config.json` wasn't updated
 2. **Solution**: Either:
-   - Revert the changes: `git restore versions.json && rm -rf versioned_docs/ versioned_sidebars/`
-   - Then use the correct command: `yarn version:add:docs <version>`
+   - Revert the changes: `git restore user_docs_versions.json && rm -rf user_docs_versioned_docs/ user_docs_versioned_sidebars/`
+   - Then use the correct command: `yarn version:add:user_docs <version>`
 
 For other issues:
 - **Restart the server**: Changes to version configuration require a server restart

docs/docusaurus.config.ts

@@ -36,6 +36,42 @@ const versionsConfig = JSON.parse(fs.readFileSync(versionsConfigPath, 'utf8'));
 // Build plugins array dynamically based on disabled flags
 const dynamicPlugins = [];
 
+// Add user_docs (formerly the preset-classic default docs instance) as an
+// explicit plugin instance, so its versioned dirs follow the same
+// `<id>_versioned_docs` / `<id>_versioned_sidebars` / `<id>_versions.json`
+// naming as the other sections instead of the bare `versioned_*` prefix
+// Docusaurus uses for the default plugin id.
+if (!versionsConfig.user_docs.disabled) {
+  dynamicPlugins.push([
+    '@docusaurus/plugin-content-docs',
+    {
+      id: 'user_docs',
+      path: 'docs',
+      routeBasePath: 'user-docs',
+      sidebarPath: require.resolve('./sidebars.js'),
+      editUrl: ({ versionDocsDirPath, docPath }: { versionDocsDirPath: string; docPath: string }) => {
+        if (docPath === 'intro.md') {
+          return 'https://github.com/apache/superset/edit/master/README.md';
+        }
+        return `https://github.com/apache/superset/edit/master/docs/${versionDocsDirPath}/${docPath}`;
+      },
+      remarkPlugins: [remarkImportPartial, remarkLocalizeBadges, remarkTechArticleSchema],
+      admonitions: {
+        keywords: ['note', 'tip', 'info', 'warning', 'danger', 'resources'],
+        extendDefaults: true,
+      },
+      docItemComponent: '@theme/DocItem',
+      includeCurrentVersion: versionsConfig.user_docs.includeCurrentVersion,
+      lastVersion: versionsConfig.user_docs.lastVersion,
+      onlyIncludeVersions: versionsConfig.user_docs.onlyIncludeVersions,
+      versions: versionsConfig.user_docs.versions,
+      disableVersioning: false,
+      showLastUpdateAuthor: true,
+      showLastUpdateTime: true,
+    },
+  ]);
+}
+
 // Add components plugin if not disabled
 if (!versionsConfig.components.disabled) {
   dynamicPlugins.push([
@@ -703,29 +739,12 @@ const config: Config = {
     [
       '@docusaurus/preset-classic',
       {
-        docs: {
-          routeBasePath: 'user-docs',
-          sidebarPath: require.resolve('./sidebars.js'),
-          editUrl: ({ versionDocsDirPath, docPath }) => {
-            if (docPath === 'intro.md') {
-              return 'https://github.com/apache/superset/edit/master/README.md';
-            }
-            return `https://github.com/apache/superset/edit/master/docs/${versionDocsDirPath}/${docPath}`;
-          },
-          remarkPlugins: [remarkImportPartial, remarkLocalizeBadges, remarkTechArticleSchema],
-          admonitions: {
-            keywords: ['note', 'tip', 'info', 'warning', 'danger', 'resources'],
-            extendDefaults: true,
-          },
-          includeCurrentVersion: versionsConfig.docs.includeCurrentVersion,
-          lastVersion: versionsConfig.docs.lastVersion,  // Make 'next' the default
-          onlyIncludeVersions: versionsConfig.docs.onlyIncludeVersions,
-          versions: versionsConfig.docs.versions,
-          disableVersioning: false,
-          showLastUpdateAuthor: true,
-          showLastUpdateTime: true,
-          docItemComponent: '@theme/DocItem',
-        },
+        // The user-docs section is configured as an explicit plugin
+        // instance above (id: 'user_docs') rather than the preset's
+        // default docs slot, so that all four sections use parallel
+        // `<id>_versioned_docs` / `<id>_versioned_sidebars` /
+        // `<id>_versions.json` naming on disk.
+        docs: false,
         blog: {
           showReadingTime: true,
           // Please change this to your repo.

docs/package.json

@@ -33,11 +33,11 @@
     "lint:docs-links": "node scripts/lint-docs-links.mjs",
     "version:add": "node scripts/manage-versions.mjs add",
     "version:remove": "node scripts/manage-versions.mjs remove",
-    "version:add:docs": "node scripts/manage-versions.mjs add docs",
+    "version:add:user_docs": "node scripts/manage-versions.mjs add user_docs",
     "version:add:admin_docs": "node scripts/manage-versions.mjs add admin_docs",
     "version:add:developer_docs": "node scripts/manage-versions.mjs add developer_docs",
     "version:add:components": "node scripts/manage-versions.mjs add components",
-    "version:remove:docs": "node scripts/manage-versions.mjs remove docs",
+    "version:remove:user_docs": "node scripts/manage-versions.mjs remove user_docs",
     "version:remove:admin_docs": "node scripts/manage-versions.mjs remove admin_docs",
     "version:remove:developer_docs": "node scripts/manage-versions.mjs remove developer_docs",
     "version:remove:components": "node scripts/manage-versions.mjs remove components"

docs/scripts/manage-versions.mjs

@@ -34,7 +34,7 @@ const rawArgs = process.argv.slice(2);
 const skipGenerate = rawArgs.includes('--skip-generate');
 const args = rawArgs.filter((a) => a !== '--skip-generate');
 const command = args[0]; // 'add' or 'remove'
-const section = args[1]; // 'docs', 'admin_docs', 'developer_docs', or 'components'
+const section = args[1]; // 'user_docs', 'admin_docs', 'developer_docs', or 'components'
 const version = args[2]; // version string like '1.2.0'
 
 function loadConfig() {
@@ -54,13 +54,13 @@ function freezeDataImports(section, version) {
   // historical version's content silently changes whenever the data file
   // is updated. Copy each escaping data import into a snapshot-local
   // `_versioned_data/` dir and rewrite the import to point there.
-  const sectionRoot = section === 'docs'
-    ? path.join(__dirname, '..', 'docs')
-    : path.join(__dirname, '..', section);
+  // The user_docs section's source content lives in `docs/docs/` (the
+  // historical folder name), while admin_docs / developer_docs /
+  // components match their plugin id 1:1.
+  const sectionDir = section === 'user_docs' ? 'docs' : section;
+  const sectionRoot = path.join(__dirname, '..', sectionDir);
   const docsRoot = path.join(__dirname, '..');
-  const versionedDocsDir = section === 'docs'
-    ? `versioned_docs/version-${version}`
-    : `${section}_versioned_docs/version-${version}`;
+  const versionedDocsDir = `${section}_versioned_docs/version-${version}`;
   const versionedDocsPath = path.join(__dirname, '..', versionedDocsDir);
   const frozenDataDir = path.join(versionedDocsPath, '_versioned_data');
 
@@ -148,9 +148,7 @@ function fixVersionedImports(section, version) {
   // Versioned content lands one directory deeper than the source content,
   // so any `../../src/` or `../../data/` imports in .md/.mdx files need
   // an extra `../` to keep reaching docs/src and docs/data.
-  const versionedDocsDir = section === 'docs'
-    ? `versioned_docs/version-${version}`
-    : `${section}_versioned_docs/version-${version}`;
+  const versionedDocsDir = `${section}_versioned_docs/version-${version}`;
   const versionedDocsPath = path.join(__dirname, '..', versionedDocsDir);
 
   if (!fs.existsSync(versionedDocsPath)) {
@@ -238,9 +236,7 @@ function addVersion(section, version) {
   }
 
   // Run Docusaurus version command
-  const docusaurusCommand = section === 'docs'
-    ? `yarn docusaurus docs:version ${version}`
-    : `yarn docusaurus docs:version:${section} ${version}`;
+  const docusaurusCommand = `yarn docusaurus docs:version:${section} ${version}`;
 
   try {
     execSync(docusaurusCommand, { stdio: 'inherit' });
@@ -262,10 +258,9 @@ function addVersion(section, version) {
   config[section].onlyIncludeVersions.splice(versionIndex, 0, version);
 
   // Add version metadata
-  const versionPath = section === 'docs' ? version : version;
   config[section].versions[version] = {
     label: version,
-    path: versionPath,
+    path: version,
     banner: 'none'
   };
 
@@ -305,13 +300,8 @@ function removeVersion(section, version) {
   console.log(`Removing version ${version} from ${section}...`);
 
   // Determine file paths based on section
-  const versionedDocsDir = section === 'docs'
-    ? `versioned_docs/version-${version}`
-    : `${section}_versioned_docs/version-${version}`;
-
-  const versionedSidebarsFile = section === 'docs'
-    ? `versioned_sidebars/version-${version}-sidebars.json`
-    : `${section}_versioned_sidebars/version-${version}-sidebars.json`;
+  const versionedDocsDir = `${section}_versioned_docs/version-${version}`;
+  const versionedSidebarsFile = `${section}_versioned_sidebars/version-${version}-sidebars.json`;
 
   // Remove versioned files
   const docsPath = path.join(__dirname, '..', versionedDocsDir);
@@ -328,9 +318,7 @@ function removeVersion(section, version) {
   }
 
   // Update versions.json file
-  const versionsJsonFile = section === 'docs'
-    ? 'versions.json'
-    : `${section}_versions.json`;
+  const versionsJsonFile = `${section}_versions.json`;
   const versionsJsonPath = path.join(__dirname, '..', versionsJsonFile);
 
   if (fs.existsSync(versionsJsonPath)) {
@@ -377,14 +365,14 @@ Usage:
   node scripts/manage-versions.mjs remove <section> <version>
 
 Where:
-  - section: 'docs', 'developer_docs', 'admin_docs', or 'components'
+  - section: 'user_docs', 'admin_docs', 'developer_docs', or 'components'
   - version: version string (e.g., '1.2.0', '2.0.0')
   - --skip-generate: skip refreshing auto-generated docs before snapshotting
                      (use when you've already placed a fresh databases.json
                      from CI and want to preserve it)
 
 Examples:
-  node scripts/manage-versions.mjs add docs 2.0.0
+  node scripts/manage-versions.mjs add user_docs 2.0.0
   node scripts/manage-versions.mjs add developer_docs 1.3.0
   node scripts/manage-versions.mjs remove components 1.0.0
 `);

docs/src/theme/DocVersionBadge/index.js

@@ -31,17 +31,15 @@ import { DownOutlined } from '@ant-design/icons';
 import styles from './styles.module.css';
 
 // Map each versioned plugin id to the URL prefix it actually serves
-// content from. Three of the four routeBasePath values differ from
-// their pluginId — the default preset-classic docs plugin lives at
-// `/user-docs`, and admin_docs / developer_docs use hyphens in their
-// URLs even though the plugin ids use underscores. Without this map
-// the basePath derivation below would mis-split the pathname for
-// those sections and the version dropdown would jump to the section
-// root instead of preserving the current page.
+// content from. The plugin ids use underscores while several
+// routeBasePath values use hyphens (and `user_docs` → `/user-docs`),
+// so without this map the basePath derivation below would mis-split
+// the pathname for those sections and the version dropdown would
+// jump to the section root instead of preserving the current page.
 //
 // Keep in sync with the `routeBasePath` values in docusaurus.config.ts.
 const PLUGIN_ID_TO_BASE_PATH = {
-  default: '/user-docs',
+  user_docs: '/user-docs',
   components: '/components',
   admin_docs: '/admin-docs',
   developer_docs: '/developer-docs',

docs/versions-config.json

@@ -1,5 +1,5 @@
 {
-  "docs": {
+  "user_docs": {
     "disabled": false,
     "lastVersion": "current",
     "includeCurrentVersion": true,