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

$3

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,
],
},
},
],
],
};
`

$3

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

$3

A simple task without hints or solutions:

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

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

::::
`

$3

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

::::
`

$3

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 });
}
\\\
:::

::::
`

$3

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

::::
`

$3

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

::::
`

$3

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

$3

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

:::

::::
`

$3

#### TaskProgression

Display progress for a specific document:

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


`

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:

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


`

Props:

- pluginId (string, optional) - Used for Docs Multi-instance ID (default: "default")

$3

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.

$3

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

$3

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

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

$3

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,
],
},
],
],
};
`

$3

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 in a community docs instance, it automatically uses pluginId="community". To reference tasks from a different instance, specify pluginId explicitly:

`mdx


`

How It Works

$3

- 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

$3

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

$3

The TaskProgression component supports multiple path formats:

`mdx



``