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

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:

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:

::::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:

::::task[Create a Component]

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

::::

Task with Hint

Add a hint to guide users:

::::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:

::::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:

::::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:

::::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:

::::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.

::::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:

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 ID (default: "default")

TaskProgressionOverview

Display progress across all documents:

import TaskProgressionOverview from "@theme/TaskProgressionOverview";

<TaskProgressionOverview pluginId="default" />

Props:

• pluginId (string, optional) - Used for 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:

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:

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:

• 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:

<!-- 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:

<!-- 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" />