npm package: @sp-days-framework/docusaurus-plugin-interactive-tasks
Description: A Docusaurus plugin for interactive task components with progress tracking
Author: SP-Days Framework
Latest version: 1.1.2

# Docusaurus Interactive Tasks Plugin

A Docusaurus plugin that transforms documentation into interactive learning experiences with tasks, hints, solutions, expected outputs, and automatic progress tracking.

## Features

- **Interactive Tasks** - Collapsible task components with completion tracking
- **Hints, Solutions & Expected Outputs** - Optional toggleable hints, solutions, and expected outputs for each task
- **Auto-Numbering** - Automatic task numbering per page
- **Persistent Progress** - Completion status saved to localStorage
- **Progress Tracking** - Visual progress indicators in sidebar and task progression components
- **Sidebar Badges** - Automatic completion badges (e.g., "2/5") in sidebar navigation
- **Auto-Collapse Toggle** - Navbar button to enable/disable auto-collapsing of completed tasks
- **Task Examples** - Non-persistent example tasks for demonstrations
- **Standard Markdown Support** - Full support for Docusaurus admonitions and markdown features within tasks

## Installation

```bash
npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
```

## Quick Start

### 1. Configure Docusaurus

Add the plugin and remark plugin to your `docusaurus.config.js`:

```js
module.exports = {
  plugins: ["@sp-days-framework/docusaurus-plugin-interactive-tasks"],

  presets: [
    [
      "classic",
      {
        docs: {
          beforeDefaultRemarkPlugins: [
            require("@sp-days-framework/docusaurus-plugin-interactive-tasks")
              .remarkTaskDirective,
          ],
        },
      },
    ],
  ],
};
```

### 2. Create Your First Task

Use directive syntax in your MDX files:

```mdx
::::task[Setup Your Environment]

Install Node.js and npm. Verify the installation:

- `node --version`
- `npm --version`

:::hint
Check the official Node.js website for installation instructions.
:::

:::solution
Download from https://nodejs.org/. npm is included with Node.js.
:::

::::
```

**Syntax Rules:**

- Use **4 colons** (`::::`) for task containers
- Use **3 colons** (`:::`) for hint, solution, and output blocks
- Tasks are automatically numbered within each page
- Completion state persists across sessions
- **Expected Output** blocks use success color theme (`--ifm-color-success`)

## Usage

### Basic Task

A simple task without hints or solutions:

```mdx
::::task[Create a Component]

Create a new React component in `src/components/MyComponent.tsx`.

::::
```

### Task with Hint

Add a hint to guide users:

```mdx
::::task[Configure TypeScript]

Set up TypeScript configuration for strict mode.

:::hint
Look for the `tsconfig.json` file in your project root.
:::

::::
```

### Task with Hint and Solution

Provide both a hint and complete solution:

```mdx
::::task[Add API Route]

Create a new API endpoint for user authentication.

:::hint
API routes in Next.js go in the `app/api` directory.
:::

:::solution
Create `app/api/auth/route.ts`:

\`\`\`typescript
export async function POST(request: Request) {
const body = await request.json();
// Authentication logic here
return Response.json({ success: true });
}
\`\`\`
:::

::::
```

### Task with Expected Output

Show users what output they should expect:

```mdx
::::task[Run Docker Container]

Start a new nginx container in detached mode on port 8080.

:::output
\`\`\`bash
$ docker run -d -p 8080:80 nginx
a3f5c8b9d2e1f4a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
\`\`\`

Visit `http://localhost:8080` and you should see the nginx welcome page.
:::

::::
```

### Task with All Features

Combine hint, solution, and expected output:

```mdx
::::task[Build Application]

Build the application and verify it works.

:::hint
Use the npm script defined in `package.json`.
:::

:::solution
\`\`\`bash
npm run build
npm run test
\`\`\`
:::

:::output
\`\`\`bash
$ npm run build
> Building application...
> ✓ Compiled successfully

$ npm run test
> Running tests...
> ✓ All tests passed (12/12)
\`\`\`
:::

::::
```

### Task Examples (Non-Persistent)

For demonstration purposes, use task examples that don't save completion state:

```mdx
::::task-example[Optional Task]

This task won't save its completion state to localStorage.

:::hint
Perfect for examples or optional exercises.
:::

::::
```

**Key Differences from Regular Tasks:**
- Uses `::::task-example` instead of `::::task`
- Displays "Example N" numbering instead of "Task N"
- Completion state is not persisted to localStorage
- Not included in task registry or progress tracking
- Ideal for demonstrations, tutorials, or non-critical exercises

### Using Docusaurus Features Inside Tasks

Tasks fully support standard Docusaurus markdown features and admonitions. You can use code blocks, tables, images, and Docusaurus admonitions (note, tip, info, warning, danger, caution, important) within task content.

```mdx
::::task[Setup Environment]

Follow these steps to configure your development environment.

:::note
Make sure you have Node.js 18+ installed before proceeding.
:::

\`\`\`bash
npm install
npm run dev
\`\`\`

:::

::::
```

### Progress Tracking Components

#### TaskProgression

Display progress for a specific document:

```mdx
import TaskProgression from "@theme/TaskProgression";

<TaskProgression path="/docs/module1" pluginId="default" />
```

**Props:**

- `path` (string, required) - Path to the document (absolute or relative)
  - Absolute: `"/docs/module1"` or `"/docs/module1.mdx"`
  - Relative: `"./sibling-doc"` or `"../parent-doc"`
  - Current page: `"."`
- `pluginId` (string, optional) - Used for [Docs Multi-instance](https://docusaurus.io/docs/docs-multi-instance) ID (default: `"default"`)

#### TaskProgressionOverview

Display progress across all documents:

```mdx
import TaskProgressionOverview from "@theme/TaskProgressionOverview";

<TaskProgressionOverview pluginId="default" />
```

**Props:**

- `pluginId` (string, optional) - Used for [Docs Multi-instance](https://docusaurus.io/docs/docs-multi-instance) ID (default: `"default"`)

### Auto-Collapse Toggle

A navbar button is automatically injected that allows users to toggle auto-collapsing of completed tasks. When enabled, completed tasks automatically collapse to reduce visual clutter.

The toggle state persists across sessions and syncs across browser tabs in real-time.

### Sidebar Badges

Task completion badges are automatically displayed in the sidebar navigation, showing progress like "2/5" for documents containing tasks. These badges:

- Update in real-time as tasks are completed
- Only appear on documents that contain tasks
- Support both individual documents and category aggregation

## Configuration

### Plugin Installation

The plugin requires **no configuration options** - it automatically discovers all Docusaurus docs instances:

```js
module.exports = {
  plugins: ["@sp-days-framework/docusaurus-plugin-interactive-tasks"],
};
```

### Remark Plugin Configuration

You must add the `remarkTaskDirective` to each docs instance's `remarkPlugins` array:

```js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Default docs instance
          beforeDefaultRemarkPlugins: [
            require('@sp-days-framework/docusaurus-plugin-interactive-tasks').remarkTaskDirective,
          ],
        },
      },
    ],
  ],
  plugins: [
    '@sp-days-framework/docusaurus-plugin-interactive-tasks',
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        // Community docs instance
        beforeDefaultRemarkPlugins: [
          require('@sp-days-framework/docusaurus-plugin-interactive-tasks').remarkTaskDirective,
        ],
      },
    ],
  ],
};
```

### Multi-Instance Support

The plugin **fully supports** [Docusaurus multi-instance docs](https://docusaurus.io/docs/docs-multi-instance):

- Automatically discovers all docs plugin instances
- Task completion state is isolated per instance
- `TaskProgression` and `TaskProgressionOverview` auto-detect the parent doc's instance
- Sidebar badges work across all instances

**Example:** If you use `<TaskProgression path="./intro.mdx" />` in a `community` docs instance, it automatically uses `pluginId="community"`. To reference tasks from a different instance, specify `pluginId` explicitly:

```mdx
<!-- In community docs, but showing tasks from default -->
<TaskProgression path="/docs/intro.mdx" pluginId="default" />
```

## How It Works

### Task Persistence

- Task completion status is saved to `localStorage` with a unique key per task
- Keys are generated using: `task-{pluginId}-{docId}-{taskNumber}-{encodedName}`
- Progress syncs across browser tabs via storage events
- Task examples use `task-example` directive and don't persist state

### Task Registry

During build, a webpack plugin scans all MDX files for task directives and generates a registry (`task-registry.json`) containing:

- Total task count per document
- Task names and numbers
- Document metadata (title, section, permalink)

This registry powers:

- Sidebar badges showing task completion (e.g., "2/5")
- TaskProgression components
- TaskProgressionOverview component

### Path Resolution

The `TaskProgression` component supports multiple path formats:

```mdx
<!-- Absolute path -->

<TaskProgression path="/docs/module1" />

<!-- Relative to current page -->

<TaskProgression path="./sibling-page" />
<TaskProgression path="../parent-page" />

<!-- Current page -->

<TaskProgression path="." />

<!-- With file extension -->

<TaskProgression path="/docs/module1.mdx" />
```