@sp-days-framework/docusaurus-plugin-interactive-tasks 1.1.0-beta1 → 1.1.0-beta2

package/docs/changelog.mdx

@@ -1,6 +1,6 @@
 ---
 toc_max_heading_level: 2
-sidebar_position: 4
+sidebar_position: 4.1
 sidebar_label: "Change Logs"
 sidebar_custom_props:
   section: "Releases"
@@ -19,6 +19,25 @@ All packages within `@sp-days-framework` use the same version number. In some ca
 
 ---
 
+## Version 1.1.0-beta2 ![beta](https://img.shields.io/badge/release-beta-yellow)
+
+Enhanced documentation with practical examples
+
+<details>
+<summary><strong>Beta Details</strong> (2025 December 09)</summary>
+
+### Improvements
+
+- **Better Documentation**: Added new task examples with detailed output explanations
+  - Clearer demonstrations of plugin capabilities
+  - More practical usage examples for common scenarios
+- **Improved Structure**: Updated sidebar positions and added known issues documentation
+- **Visual Refinements**: Enhanced sidebar and navbar logo handling
+
+</details>
+
+---
+
 ## Version 1.1.0-beta1 ![beta](https://img.shields.io/badge/release-beta-yellow)
 
 Show expected outputs and enjoy smoother interactions

package/docs/index.mdx

@@ -1,8 +1,9 @@
 ---
 title: Interactive Tasks
 hide_title: true
+sidebar_class_name: title-logo-sidebar-docusaurus
+sidebar_label: "Interactive Tasks"
 sidebar_position: 0
-sidebar_label: "📦 Interactive Tasks"
 ---
 
 import LogoDocusaurus from './logo-docusaurus.svg';
@@ -26,6 +27,64 @@ import LogoDocusaurus from './logo-docusaurus.svg';
   </div>
 </div>
 
+<div style={{ position: 'relative', marginTop: '2rem', display: 'flex', justifyContent: 'center' }}>
+  <div style={{ position: 'absolute', left: '50%', marginTop: '4px', transform: 'translateX(-50%)', fontWeight: 500, color: 'var(--ifm-color-emphasis-600)' }}>
+    Preview
+  </div>
+  <div id="preview-task-example" style={{ borderRadius: '12px', padding: '2rem 1.7rem 0rem', background: 'var(--ifm-color-emphasis-200)' }}>
+    <style>{`
+      #preview-task-example h3 {
+        display: none !important;
+      }
+    `}</style>
+    ::::task-example[Calibrate the Flux Capacitor ⚡]
+
+    Great Scott, Marty! We need to recalibrate the **temporal documentation flux capacitor** to 1.21 gigawatts! 
+    
+    1. Check the chronosync matrix for para-dimensional efficiency
+    2. Initiate the **quantum state persistence protocol**
+    3. Engage the localStorage temporal buffer
+    4. Restart the cross-timeline synchronization array by running the following command:
+      ```bash
+      sudo systemctl restart ntpd
+      ```
+
+    :::hint
+    The "Mark as Done" actuator button is located in the down-right quadrant of the task containment field. A simple click should energize the completion state capacitor!
+    :::
+
+    :::output
+    If done correctly, you should observe the following temporal anomalies:
+    
+    ```
+    ⚡ Flux capacitor status: ENGAGED
+    📊 Temporal progress vector: SYNCHRONIZED
+    💾 localStorage quantum buffer: PERSISTED
+    ✅ Task completion waveform: COLLAPSED TO TRUE STATE
+    ```
+
+    Heavy! Your progress just traveled through time! 🚗💨
+    :::
+
+    :::solution
+    When you check that box, the plugin harnesses the power of localStorage to preserve your completion state across multiple timeline iterations (browser sessions). 
+    
+    The temporal data persists even if you reload the page or jump to a different tab - it's like the DeLorean maintaining 88 mph across different roads! 
+    
+    Key features of the completion tracking system:
+    - **Persistent storage** across browser sessions
+    - **Real-time synchronization** between tabs
+    - **Automatic state management** for your learning progress
+    - **Cross-dimensional compatibility** (works in any timeline!)
+    
+    *This is heavy... but in a good way!* 🎸
+    :::
+
+    ::::
+  </div>
+</div>
+<br/>
+
 ---
 
 ## Features
@@ -51,6 +110,16 @@ Install the Interactive Tasks plugin using npm or yarn.
 Use npm install or yarn add to install the package.
 :::
 
+:::output
+You should see output similar to:
+
+```
+added 1 package, and audited 2 packages in 3s
+
+found 0 vulnerabilities
+```
+:::
+
 :::solution
 ```bash
 npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
@@ -60,33 +129,31 @@ npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
 ::::
 ````
 
-<div style={{ position: 'relative', marginTop: '2rem', display: 'flex', justifyContent: 'center' }}>
-  <div style={{ position: 'absolute', left: '50%', marginTop: '4px', transform: 'translateX(-50%)', fontWeight: 500, color: 'var(--ifm-color-emphasis-600)' }}>
-    Preview
-  </div>
-  <div id="preview-task-example" style={{ borderRadius: '12px', padding: '2rem 2rem 0rem 2rem', background: 'var(--ifm-color-emphasis-200)' }}>
-    <style>{`
-      #preview-task-example h3 {
-        display: none !important;
-      }
-    `}</style>
-    ::::task-example[Install the Plugin]
+::::task-example[Install the Plugin]
 
-    Install the Interactive Tasks plugin using npm or yarn.
+Install the Interactive Tasks plugin using npm or yarn.
 
-    :::hint
-    Use npm install or yarn add to install the package.
-    :::
+:::hint
+Use npm install or yarn add to install the package.
+:::
 
-    :::solution
-    ```bash
-    npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
-    ```
-    :::
+:::output
+You should see output similar to:
+
+```
+added 1 package, and audited 2 packages in 3s
+
+found 0 vulnerabilities
+```
+:::
+
+:::solution
+```bash
+npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
+```
+:::
+
+::::
 
-    ::::
-  </div>
-</div>
-<br/>
 
 Tasks are automatically numbered, track completion in localStorage, and sync across browser tabs. See [Install](install.mdx) for installation and configuration.

package/docs/known-issues.mdx

@@ -0,0 +1,164 @@
+---
+toc_max_heading_level: 2
+sidebar_position: 4.2
+sidebar_custom_props:
+  section: "Releases"
+  section_position: 4
+---
+
+# Known Issues
+
+## Theme Resolution Chain Breaking
+
+### Overview
+
+The Interactive Tasks plugin does not follow Docusaurus best practices for theme swizzling. The current implementation swizzles `DocRoot` using direct imports from `@docusaurus/theme-classic`, which bypasses Docusaurus's theme resolution system. This causes compatibility issues when used alongside other plugins that also swizzle MDX components.
+
+### Technical Explanation
+
+#### How Docusaurus Theme Resolution Works
+
+Docusaurus uses webpack aliases (`@theme/*` and `@theme-original/*`) to create a resolution chain when multiple plugins swizzle the same component:
+
+```
+User Site
+  ↓ @theme/MDXComponents
+Plugin A's MDXComponents
+  ↓ @theme-original/MDXComponents
+Plugin B's MDXComponents
+  ↓ @theme-original/MDXComponents
+Theme-Classic Base Components
+```
+
+Each plugin receives the previous plugin's components and can add or modify them, creating a merged component set.
+
+#### Why This Plugin Breaks the Chain
+
+The Interactive Tasks plugin swizzles `DocRoot` to provide the `TaskProvider` context that wraps the entire docs layout:
+
+```tsx
+// This direct import bypasses theme resolution
+import OriginalDocRoot from '@docusaurus/theme-classic/lib/theme/DocRoot';
+```
+
+**Why we use direct imports:**
+- Importing via `@theme-original/DocRoot` would create infinite recursion if we're the only plugin swizzling DocRoot
+- DocRoot needs to wrap both sidebar and content for task progress tracking
+- Alternative components like `Root` don't provide access to docs-specific context
+
+**Side effects:**
+- Direct imports bypass webpack's theme alias system
+- This creates inconsistencies in the module resolution graph
+- Subsequent `@theme-original/*` imports in other plugins may fail to resolve correctly
+- Standard MDX components may not propagate through the theme chain
+
+#### Current Workaround
+
+To compensate for breaking the theme chain, this plugin's `MDXComponents.tsx` explicitly imports and re-exports all standard components:
+
+```tsx
+// Defensive imports to maintain component availability
+import MDXCode from '@docusaurus/theme-classic/lib/theme/MDXComponents/Code';
+import MDXDetails from '@docusaurus/theme-classic/lib/theme/MDXComponents/Details';
+// ... etc
+```
+
+This ensures that standard components (`Details`, `Code`, `Pre`, etc.) plus task components (`Task`, `Hint`, `Solution`, etc.) are available in MDX files.
+
+### Impact on Other Plugins
+
+When another plugin loads after Interactive Tasks and tries to swizzle `MDXComponents`:
+
+1. The other plugin imports `@theme-original/MDXComponents`
+2. Due to the broken chain, it may not receive all expected components
+3. Standard components like `Details` might be missing
+4. Task components might not be available
+
+**Workaround for compatible plugins:** Other plugins must adopt the same defensive pattern of explicitly importing standard components from theme-classic.
+
+### Affected Scenarios
+
+This issue manifests when:
+
+- Multiple plugins swizzle `MDXComponents`
+- Pages use standard MDX components (`<details>`, code blocks, etc.)
+- Pages use Interactive Tasks components (`<Task>`, `<Hint>`, etc.)
+
+**Symptoms:**
+- Build failures with "Expected component to be defined" errors
+- Components missing at runtime
+- Inconsistent component availability across different pages
+
+### Future Plans
+
+#### Short-term
+We're maintaining the current implementation because:
+- It works reliably when plugins follow the defensive pattern
+- The functionality (task progress tracking across sidebar and content) requires this scope
+- Migration would be a breaking change for existing users
+
+#### Long-term (Docusaurus 4.0+)
+We plan to refactor the plugin to follow best practices:
+
+**Option 1: Site-level Root Component**
+Remove `DocRoot` swizzle and require users to add `TaskProvider` in their site's `src/theme/Root.tsx`:
+
+```tsx
+import React from 'react';
+import { TaskProvider } from '@sp-days-framework/docusaurus-plugin-interactive-tasks';
+
+export default function Root({ children }) {
+  return <TaskProvider>{children}</TaskProvider>;
+}
+```
+
+**Pros:**
+- Restores proper theme resolution
+- Eliminates direct imports
+- More maintainable
+
+**Cons:**
+- Breaking change
+- Additional setup for users
+- May not have docs-specific context
+
+**Option 2: Docusaurus 4.0 APIs**
+Wait for Docusaurus 4.0 which may provide:
+- Better support for context providers
+- Dedicated hooks for global context
+- Clearer theme composition boundaries
+
+### Compatibility Guidelines
+
+If you're developing plugins that work alongside Interactive Tasks:
+
+1. **Import standard components explicitly** in your `MDXComponents.tsx`:
+   ```tsx
+   import MDXDetails from '@docusaurus/theme-classic/lib/theme/MDXComponents/Details';
+   import MDXCode from '@docusaurus/theme-classic/lib/theme/MDXComponents/Code';
+   // ... other standard components
+   ```
+
+2. **Re-export all components** including those from `@theme-original`:
+   ```tsx
+   export default {
+     ...MDXComponents,
+     details: MDXDetails,
+     code: MDXCode,
+     // Your custom components
+   };
+   ```
+
+3. **Test with Interactive Tasks** enabled to ensure compatibility
+
+### Related Documentation
+
+- [Docusaurus Swizzling Guide](https://docusaurus.io/docs/swizzling)
+- [Wrapping your site with Root](https://docusaurus.io/docs/swizzling#wrapper-your-site-with-root)
+- See `/PLUGIN-ISSUES.md` in the repository root for detailed technical analysis
+
+---
+
+**Last Updated:** December 9, 2025  
+**Status:** No immediate fix planned, monitoring Docusaurus 4.0 development
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sp-days-framework/docusaurus-plugin-interactive-tasks",
-  "version": "1.1.0-beta1",
+  "version": "1.1.0-beta2",
   "description": "A Docusaurus plugin for interactive task components with progress tracking",
   "repository": {
     "type": "git",

package/publish-package-docs.js

@@ -12,9 +12,9 @@ module.exports = {
   beforeDefaultRemarkPlugins: [
     [
       require("./lib/index.js").remarkTaskDirective,
-      { 
+      {
         tocHeadingLevel: 3,
-      }
+      },
     ],
   ],
 };