product versions added to header

Author: jtviolet

.claude/commands/add-version.md

@@ -1,45 +1,100 @@
 # Add New Version to Existing Product
 
-This command helps you quickly add a new version to an existing product in the documentation.
+This command helps you quickly add a new version to an existing product in the Netwrix documentation site built on Docusaurus v3.
 
-## Steps to Complete
+## Quick Reference
 
-1. **Gather Information**
-   - Ask user for product name (e.g., "accessanalyzer", "threatprevention")
-   - Ask for new version number (e.g., "12.1", "7.6")
-   - Identify the current latest version by checking existing directories
+**Command Pattern**: `npm start {productname}/{new_version}` to test
+**Key Files**: 
+- `/docs/{productname}/{version}/` - Documentation files
+- `/sidebars/{productname}/{version}.js` - Sidebar configuration
+- `docusaurus.config.js` - Plugin configuration
+- `/src/components/HomepageFeatures/index.js` - Version badges
+- `/static/img/product_docs/{productname}/{version}/` - Images
 
-2. **Copy Documentation from Latest Version**
+---
+
+## Complete Step-by-Step Process
+
+### 1. **Gather Information & Validate**
+   
+   **Ask user for:**
+   - Product name (e.g., "accessanalyzer", "identitymanager")
+   - New version number (e.g., "12.1", "6.3")
+   
+   **Validate existing structure:**
    ```bash
-   # Find latest version
-   ls -d /docs/{productname}/*/ | sort -V | tail -1
+   # Check existing versions
+   ls -d docs/{productname}/*/ | sort -V
 
-   # Copy to new version
-   cp -r /docs/{productname}/{latest_version}/ /docs/{productname}/{new_version}/
+   # Verify latest version
+   ls -d docs/{productname}/*/ | sort -V | tail -1
    ```
 
-3. **Update Frontmatter in Copied Files**
-   - Update version references in all `.md` files
-   - Update any version-specific content in whatsnew.md
+### 2. **Create Documentation Directory**
+   
+   **Create new version directory:**
+   ```bash
+   # Create new version directory structure
+   mkdir -p docs/{productname}/{new_version}
+   
+   # Create basic index.md file
+   cat > docs/{productname}/{new_version}/index.md << 'EOF'
+---
+title: '{Product Name} {new_version}'
+sidebar_label: "What's New"
+description: '{Product Name} {new_version} documentation'
+---
+
+# {Product Name} {new_version}
 
-4. **Create New Sidebar Configuration**
+* content to be added *
+EOF
+   ```
+   
+   **Verify directory created:**
    ```bash
-   cp /sidebars/{productname}-{latest_version}-sidebar.js /sidebars/{productname}-{new_version}-sidebar.js
+   ls -la docs/{productname}/{new_version}/
    ```
+
+### 3. **Create Image Directory**
 
-   Update the sidebar file if it contains version-specific paths.
+   ```bash
+   # Create version-specific image directory
+   mkdir -p static/img/product_docs/{productname}/{new_version}
+   ```
 
-5. **Add to docusaurus.config.js**
+### 4. **Create Sidebar Configuration**
+   
+   **Set up sidebar directory structure:**
+   ```bash
+   # Create sidebar directory if it doesn't exist
+   mkdir -p sidebars/{productname}
+   
+   # Create new sidebar configuration file
+   cat > sidebars/{productname}/{new_version}.js << 'EOF'
+module.exports = {
+  productSidebar: [
+    {
+      type: 'autogenerated',
+      dirName: '.',
+    },
+  ],
+};
+EOF
+   ```
+   
+### 5. **Add Docusaurus Plugin Configuration**
 
-   Add new plugin configuration after the existing versions:
    ```javascript
+   // Add this block AFTER existing versions, before the closing ];
    [
      '@docusaurus/plugin-content-docs',
      {
-       id: '{productname}{version_underscores}',  // e.g., 'accessanalyzer12_1'
+       id: '{productname}{version_with_underscores}',  // e.g., 'accessanalyzer12_1'
        path: 'docs/{productname}/{version}',
        routeBasePath: 'docs/{productname}/{version}',
-       sidebarPath: require.resolve('./sidebars/{productname}-{version}-sidebar.js'),
+       sidebarPath: require.resolve('./sidebars/{productname}/{version}.js'),
        editUrl: 'https://github.com/netwrix/docs/tree/main/',
        exclude: ['**/CLAUDE.md'],
        versions: {
@@ -50,39 +105,189 @@ This command helps you quickly add a new version to an existing product in the d
      },
    ],
    ```
+   
+   **Important Notes:**
+   - Convert dots to underscores in ID: `12.1` → `12_1`
+   - Use exact version number in path
+   - Point to the correct sidebar file
 
-6. **Update HomepageFeatures Component**
+### 6. **Update HomepageFeatures Component**
 
-   Find the product in `/src/components/HomepageFeatures/index.js` and update the link to point to the new version:
+   **Update version badges in `/src/components/HomepageFeatures/index.js`:**
+   
+   Find the product in the appropriate category and update:
    ```javascript
    {
-     title: '{Product Name}',
-     link: '/docs/{productname}/{new_version}',  // Update to new version
-     description: '{product description}'
-   },
+     name: '{Product Name}',
+     description: '{product description}',
+     link: '/docs/{productname}/{new_version}',  // ← Update main link
+     versions: [
+       { version: '{new_version}', link: '/docs/{productname}/{new_version}', isLatest: true },  // ← Add new
+       { version: '{old_latest}', link: '/docs/{productname}/{old_latest}', isLatest: false }, // ← Update
+       { version: '{older_version}', link: '/docs/{productname}/{older_version}', isLatest: false },
+       // ... other versions
+     ],
+   }
    ```
 
-7. **Test the New Version**
+### 7. **Test the New Version**
+   
+   **Start development server:**
    ```bash
+   # Test single product mode (recommended)
    npm start {productname}/{new_version}
    ```
+   
+---
+
+## Examples
+
+### Example 1: Adding Access Analyzer 12.1
+
+```bash
+# 1. Create new documentation directory
+mkdir -p docs/accessanalyzer/12.1
+# Create index.md with Access Analyzer 12.1 content
+
+# 2. Create images directory
+mkdir -p static/img/product_docs/accessanalyzer/12.1
+touch static/img/product_docs/accessanalyzer/12.1/.gitkeep
+
+# 3. Create sidebar
+mkdir -p sidebars/accessanalyzer
+# Create sidebars/accessanalyzer/12.1.js with standard structure
+
+# 4. Update docusaurus.config.js - Add plugin with ID: 'accessanalyzer12_1'
+
+# 5. Update HomepageFeatures - Change link to '/docs/accessanalyzer/12.1'
+
+# 6. Test
+npm start accessanalyzer/12.1
+```
+
+### Example 2: Adding Identity Manager 6.3
+
+```bash
+# 1. Create new documentation directory
+mkdir -p docs/identitymanager/6.3
+# Create index.md with Identity Manager 6.3 content
+
+# 2. Create images directory
+mkdir -p static/img/product_docs/identitymanager/6.3
+touch static/img/product_docs/identitymanager/6.3/.gitkeep
+
+# 3. Create sidebar
+mkdir -p sidebars/identitymanager
+# Create sidebars/identitymanager/6.3.js with standard structure
+
+# 4. Update docusaurus.config.js - Add plugin with ID: 'identitymanager6_3'
+
+# 5. Update HomepageFeatures - Change link to '/docs/identitymanager/6.3'
+
+# 6. Test
+npm start identitymanager/6.3
+```
+
+---
+
+## Configuration Patterns
+
+### Plugin ID Naming Convention
+- **Dots to underscores**: `12.1` → `12_1`
+- **Pattern**: `{productname}{version_underscores}`
+- **Examples**: 
+  - `accessanalyzer12_1`
+  - `identitymanager6_3`  
+  - `endpointprotector5_9_4_3`
+
+### Sidebar File Patterns
+- **Standard**: `./sidebars/{productname}/{version}.js`
+- **Generic fallback**: `./sidebars/sidebar.js`
+- **Legacy pattern**: `./sidebars/{productname}-{version}-sidebar.js` (still supported)
+
+### Version Badge System
+- **Latest version**: Green badge with `isLatest: true`
+- **Older versions**: Blue badges with `isLatest: false`  
+- **Display format**: "v{version}" (e.g., "v12.1")
+
+---
+
+## Important Reminders
+
+### Before You Start
+- ✅ Use single-product mode: `npm start {productname}/{version}` for faster development
+- ✅ Create fresh documentation structure for the new version
+- ✅ Create version-specific image directories
+- ✅ Test thoroughly before committing
+
+### Configuration Rules
+- ✅ Version dots → underscores in plugin IDs
+- ✅ Always exclude `['**/CLAUDE.md']` in plugin config
+- ✅ Update main link AND versions array in HomepageFeatures
+- ✅ Use `.webp` format for images when possible
+
+### Quality Assurance
+- ✅ Run `npm run format` before committing
+- ✅ Test dark mode appearance
+- ✅ Verify all navigation links work
+- ✅ Check version badges display correctly
+- ✅ Ensure images load from correct directories
+
+### Common Issues
+- 🚫 **Port conflicts**: Default runs on port 3000
+- 🚫 **Memory issues**: Already configured with 8GB limit  
+- 🚫 **Cache problems**: Run `npm run clear` to reset
+- 🚫 **Hot reload failure**: Restart dev server
+- 🚫 **Missing images**: Check image directory paths match version
+
+---
+
+## Troubleshooting
+
+### Build Failures
+```bash
+# Clear all caches
+npm run clear
+rm -rf .docusaurus
+
+# Restart with fresh cache
+npm start {productname}/{version}
+```
+
+### Missing Sidebar
+```bash
+# Check if sidebar file exists
+ls -la sidebars/{productname}/{version}.js
+
+# Copy from generic if missing
+cp sidebars/sidebar.js sidebars/{productname}/{version}.js
+```
+
+### Image Not Loading
+```bash
+# Verify image directory exists
+ls -la static/img/product_docs/{productname}/{version}/
+
+# Check image paths in markdown (should be absolute)
+grep -r "img/product_docs" docs/{productname}/{version}/
+```
+
+### Version Badge Not Showing
+- Verify `versions` array in HomepageFeatures includes new version
+- Check `isLatest: true` is set only for the newest version
+- Ensure main `link` property points to latest version
 
-8. **Update What's New Page**
-   - Clear the content in `/docs/{productname}/{new_version}/whatsnew.md`
-   - Add placeholder for new version features
+---
 
-## Example
+## Files Modified Checklist
 
-Adding version 12.1 to Access Analyzer:
-1. Copy from 12.0: `cp -r docs/accessanalyzer/12.0/ docs/accessanalyzer/12.1/`
-2. Create sidebar: `cp sidebars/accessanalyzer-12.0-sidebar.js sidebars/accessanalyzer-12.1-sidebar.js`
-3. Add plugin with id: `accessanalyzer12_1`
-4. Update HomepageFeatures link to `/docs/accessanalyzer/12.1`
-5. Test: `npm start accessanalyzer/12.1`
+When complete, you should have modified:
 
-## Important Notes
+- [ ] `/docs/{productname}/{new_version}/` - New documentation directory
+- [ ] `/static/img/product_docs/{productname}/{new_version}/` - New images directory  
+- [ ] `/sidebars/{productname}/{new_version}.js` - New sidebar configuration
+- [ ] `docusaurus.config.js` - Added new plugin configuration
+- [ ] `/src/components/HomepageFeatures/index.js` - Updated version badges
+- [ ] `/docs/{productname}/{new_version}/whatsnew.md` - Created for new content
 
-- Version numbers use dots in paths (12.1) but underscores in IDs (12_1)
-- Always test the new version before committing
-- Update whatsnew.md with actual changes for the new version
-- Consider if any version-specific content needs updating
+**Test command**: `npm start {productname}/{new_version}`