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

package/docs/tasks.mdx

@@ -0,0 +1,433 @@
+---
+sidebar_position: 2.1
+toc_max_heading_level: 2
+sidebar_label: "Task"
+sidebar_custom_props:
+  section: "Components"
+  section_position: 2
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Task Component
+
+Learn how to create interactive tasks with various features including hints, solutions, and non-persistent examples.
+
+<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[Explore the Task Component Features]
+
+      This is an interactive task component! **Try clicking the buttons** to explore its features:
+
+      1. **Need guidance?** Click the "Show Hint" button below to reveal helpful information
+      3. **Check your work?** Click "Show Expected Output" to see what you should get
+      2. **Want the answer?** Click "Show Solution" to see the complete solution
+      4. **Mark progress**: Click "Mark as Done" to track completion
+
+      :::hint
+
+      **This is a hint section!**
+
+      Hints are perfect for providing guidance without spoiling the solution. They can contain:
+      - Tips and best practices
+      - Links to relevant documentation
+      - Reminders about important concepts
+      - Warnings about common pitfalls
+
+      You can include any markdown content here, including lists, **formatting**, and [links](https://docusaurus.io).
+
+      :::
+
+      :::output
+
+      **This is an expected output section!**
+
+      The output section uses a success color theme to help users verify their work. Use it to show:
+      - Terminal command outputs
+      - Expected console logs
+      - API responses
+      - Visual results
+
+      This helps learners confirm they've completed the task correctly!
+
+      :::
+
+      :::solution
+
+      **This is a solution section!**
+
+      Solutions show the complete answer. This is where you'd typically include:
+      - Step-by-step instructions
+      - Complete code implementations
+      - Configuration examples
+      - Verification steps
+
+      Since this is a `task-example`, your completion status won't be saved. Regular `task` components automatically persist progress to browser localStorage.
+
+      :::
+
+      ::::
+  </div>
+</div>
+
+
+
+---
+
+
+## Basic Task
+
+A simple task without hints or solutions.
+
+
+```md
+::::task[Create a Component]
+
+Create a new React component in `src/components/MyComponent.tsx`.
+
+::::
+```
+
+::::task-example[Create a Component]
+
+Create a new React component in `src/components/MyComponent.tsx`.
+
+::::
+
+
+---
+
+## Task with Hint
+
+Add a hint to guide users through the task.
+
+
+```mdx
+::::task[Configure TypeScript]
+
+Set up TypeScript configuration for strict mode.
+
+:::hint
+Look for the `tsconfig.json` file in your project root.
+:::
+
+::::
+```
+
+::::task-example[Configure TypeScript]
+
+Set up TypeScript configuration for strict mode.
+
+:::hint
+Look for the `tsconfig.json` file in your project root.
+:::
+
+::::
+
+---
+
+## Task with Solution
+
+Provide a complete solution for the task.
+
+
+```mdx
+::::task[Create Package JSON]
+
+Initialize a new Node.js project with npm.
+
+:::solution
+Run `npm init -y` in your project directory.
+:::
+
+::::
+```
+
+::::task-example[Create Package JSON]
+
+Initialize a new Node.js project with npm.
+
+:::solution
+Run `npm init -y` in your project directory.
+:::
+
+::::
+
+---
+
+## Task with Hint and Solution
+
+Combine both hint and solution for comprehensive guidance.
+
+````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-example[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 from completing the task.
+
+````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-example[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 for maximum guidance.
+
+````mdx
+::::task[Build and Test Application]
+
+Build the application and verify it works correctly.
+
+:::hint
+Use the npm script defined in `package.json` for building.
+:::
+
+:::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-example[Build and Test Application]
+
+Build the application and verify it works correctly.
+
+:::hint
+Use the npm script defined in `package.json` for building.
+:::
+
+:::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)
+```
+:::
+
+::::
+
+
+---
+
+## Using Markdown Features
+
+Tasks fully support standard Docusaurus markdown features like the [admonitions feature](https://docusaurus.io/docs/markdown-features/admonitions).
+
+
+````mdx
+::::task[Setup Development Environment]
+
+Follow these steps to configure your workspace.
+
+:::note
+Make sure you have Node.js 18+ installed before proceeding.
+:::
+
+**Installation Steps:**
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Start the development server:
+```bash
+npm run dev
+```
+
+:::warning
+Do not commit your `.env` file to version control!
+:::
+
+:::hint
+Check the README.md for environment variable examples.
+:::
+
+::::
+````
+
+::::task-example[Setup Development Environment]
+
+Follow these steps to configure your workspace.
+
+:::note
+Make sure you have Node.js 18+ installed before proceeding.
+:::
+
+**Installation Steps:**
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Start the development server:
+```bash
+npm run dev
+```
+
+:::warning
+Do not commit your `.env` file to version control!
+:::
+
+:::hint
+Check the README.md for environment variable examples.
+:::
+
+::::
+
+## Syntax Reference
+
+| Element | Directive | Requirement | Notes |
+|---------|-----------|-------------|-------|
+| **Task Container** | `::::task[Task Name]` (4+ colons) | Required | Tasks are auto-numbered sequentially per page |
+| **Hint Section** | `:::hint` (3+ colons) | Optional | Max one per task; additional hints ignored with warning. Can appear anywhere inside task container |
+| **Solution Section** | `:::solution` (3+ colons) | Optional | Max one per task; additional solutions ignored with warning. Can appear anywhere inside task container |
+| **Expected Output Section** | `:::output` (3+ colons) | Optional | Max one per task; additional outputs ignored with warning. Can appear anywhere inside task container. Uses success color theme (`--ifm-color-success`) |
+| **Task Example** | `::::task-example[Example Name]` (4+ colons) | Required | Same as regular tasks but non-persistent; uses "Example N" numbering |
+
+## Nesting
+
+The `::::task` directive supports nesting [admonitions](https://docusaurus.io/docs/markdown-features/admonitions) and other markdown features by using colon count to determine hierarchy. Each parent container must use **more colons** than its children to prevent premature closure.
+
+**Nesting rules:**
+- Task container: `::::task` (4+ colons)
+  - Hint/Solution: `:::hint` or `:::solution` (3+ colons)
+    - Nested admonition: `:::note`, `:::tip`, etc. (3+ colons)
+    - For deeper nesting, add more colons to parent containers
+
+Each level needs more colons than its children to avoid premature closure.
+
+### Nesting Example
+
+```mdx
+::::::task[Nested Example]
+(Layer 1)
+
+:::::hint
+(Layer 2)
+
+::::note
+(Layer 3)
+
+:::warning
+(Layer 4)
+:::
+
+:::::
+
+::::::
+```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@sp-days-framework/docusaurus-plugin-interactive-tasks",
-  "version": "1.0.5-rc2",
+  "version": "1.1.0-beta2",
   "description": "A Docusaurus plugin for interactive task components with progress tracking",
   "repository": {
     "type": "git",
-    "url": "https://github.com/helse-sorost/sp-days-framework",
+    "url": "git+https://github.com/helse-sorost/sp-days-framework.git",
     "directory": "docusaurus-plugin-interactive-tasks"
   },
   "keywords": [
@@ -21,6 +21,8 @@
   "types": "lib/index.d.ts",
   "files": [
     "lib/**/*",
+    "docs/**/*",
+    "publish-package-docs.js",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +32,7 @@
       "import": "./lib/index.js",
       "types": "./lib/index.d.ts"
     },
+    "./publish-package-docs": "./publish-package-docs.js",
     "./lib/theme/*": "./lib/theme/*",
     "./lib/plugin/*": "./lib/plugin/*"
   },

package/publish-package-docs.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Sykehuspartner HF
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  id: "interactive-tasks-docs",
+  path: require("path").join(__dirname, "docs"),
+  routeBasePath: "package-docs/interactive-tasks",
+  beforeDefaultRemarkPlugins: [
+    [
+      require("./lib/index.js").remarkTaskDirective,
+      {
+        tocHeadingLevel: 3,
+      },
+    ],
+  ],
+};