@sp-days-framework/create-sp-days 1.0.4 → 1.1.0-beta1

package/docs/index.mdx

@@ -0,0 +1,205 @@
+---
+title: Create SP Days
+hide_title: true
+sidebar_label: "📦 Create SP Days"
+sidebar_position: 0
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import LogoSPDays from './sp-days-plugin-color-light.svg';
+
+<div align="center">
+  <div style={{ display: 'flex', justifyContent: 'center', margin: '1rem' }}>
+    <LogoSPDays width="110" height="110"/>
+  </div>
+  <div align="center">
+    # Create SP Days
+  </div>
+  <div align="center">
+    <p>
+      *Scaffolding tool for creating SP Days course websites!*
+    </p>
+    <h4>
+      <a href="./create-sp-days/install/">🔧 Setup</a> · 
+      <a href="https://www.npmjs.com/package/@sp-days-framework/create-sp-days">📦 NPM Package</a> · 
+      <a href="https://github.com/helse-sorost/sp-days-framework">💻 Source Code</a>
+    </h4>
+  </div>
+</div>
+
+---
+
+## Features
+
+- **Zero-Config Setup** - Get started with a fully configured course website in minutes
+- **Interactive CLI** - Guided setup process with sensible defaults
+- **Flexible Templates** - Base course structure with optional Slidev and Resources addons
+- **TypeScript Ready** - Full TypeScript support out of the box
+- **Multiple Package Managers** - Works with npm, yarn, pnpm, and bun
+- **GitHub Integration** - Pre-configured for GitHub Pages deployment
+
+## Quick Start
+
+### Interactive Mode (Recommended)
+
+Run the scaffolding tool and follow the prompts:
+
+```bash
+npx @sp-days-framework/create-sp-days
+```
+
+You'll be asked for:
+
+- **Site name** - Directory name for your project
+- **Project details** - Name, GitHub org, repository
+- **Branding** - Site title and tagline
+- **Features** - Enable Slidev presentations and/or Resources documentation
+
+### Quick Create
+
+Create a new course with one command:
+
+```bash
+npx @sp-days-framework/create-sp-days my-course
+```
+
+This creates a basic course structure in the `my-course` directory. You can customize it later.
+
+## What You Get
+
+### Base Template (Always Included)
+
+Every SP-Days course comes with:
+
+- **Docusaurus 3.x** - Modern documentation framework
+- **Interactive Tasks** - Hands-on learning exercises with built-in task tracking
+- **Frontpage Components** - Beautiful landing page components and layouts
+- **Course Structure** - Pre-configured `/course` directory ready for your content
+- **TypeScript** - Full type safety and IntelliSense support
+- **SASS Support** - Custom styling capabilities
+- **Mermaid Diagrams** - Create flowcharts, sequence diagrams, and more
+
+### Optional Addons
+
+<Tabs>
+  <TabItem value="slidev" label="Slidev Integration" default>
+    Add presentation capabilities to your course:
+
+    ```bash
+    npx @sp-days-framework/create-sp-days my-course --addon-slidev
+    ```
+
+    Includes:
+
+    - Slidev integration plugin
+    - Sykehuspartner theme
+    - Example presentations
+    - `npm run slidev` command
+  </TabItem>
+  <TabItem value="resources" label="Resources Documentation">
+    Add comprehensive documentation:
+
+    ```bash
+    npx @sp-days-framework/create-sp-days my-course --addon-resources
+    ```
+
+    Includes:
+
+    - Separate documentation instance
+    - Component usage guides
+    - Setup examples
+    - Best practices
+  </TabItem>
+  <TabItem value="package-docs" label="Package Documentation">
+    Add developer documentation for all installed plugins:
+
+    ```bash
+    npx @sp-days-framework/create-sp-days my-course --include-package-docs
+    ```
+
+    Includes:
+
+    - Plugin API documentation
+    - Developer guides
+    - Accessible via "Plugin Docs" dropdown
+    - Routes: `/package-docs/interactive-tasks`, etc.
+
+    :::info Package Documentation Feature
+    Starting from version 1.1.0, all `@sp-days-framework` packages include their documentation as pre-made Docusaurus MDX files. This feature is useful for package development and easier documentation access, but adds unnecessary dependencies for production builds.
+
+    **Note:** Enabling package documentation automatically installs the Slidev addon (even if not explicitly requested) because package docs include Slidev theme documentation.
+    :::
+  </TabItem>
+</Tabs>
+
+## Getting Started
+
+### 1. Create Your Course
+
+<Tabs>
+  <TabItem value="interactive" label="Interactive Mode" default>
+    ```bash
+    npx @sp-days-framework/create-sp-days
+    ```
+
+    Follow the prompts to configure your course. The interactive mode guides you through all options with helpful defaults and suggestions.
+  </TabItem>
+  <TabItem value="cli" label="CLI Mode">
+    ```bash
+    npx @sp-days-framework/create-sp-days docker-course \
+      --title "Docker Fundamentals" \
+      --tagline "Master containerization" \
+      --addon-slidev
+    ```
+
+    Specify all options upfront. Perfect for scripting or when you know exactly what you want.
+  </TabItem>
+</Tabs>
+
+### 2. Add Your Content
+
+Create your course content in the generated project:
+
+**Main landing page:**
+- Edit `src/pages/index.mdx` to customize your course homepage
+
+**Course modules:**
+- Add lessons in `course/` directory
+- Each `.mdx` file becomes a page
+
+**Presentations (if `--addon-slidev` enabled):**
+- Create slides in `slidev/` directory
+- Run `npm run slidev ./slidev/your-presentation.md` for live preview
+
+**Resources (if `--addon-resources` enabled):**
+- Add documentation in `resources/` directory
+
+### 3. Development
+
+Start the development server:
+
+```bash
+npm start
+```
+
+Open `http://localhost:3000` to see your course site. The server will hot-reload as you edit content.
+
+See [Installation](./install.mdx) for detailed configuration options.
+
+## Available Commands
+
+After creating your course, use these commands:
+
+| Command | Description |
+|---------|-------------|
+| `npm start` | Start development server with hot-reload |
+| `npm run build` | Build for production |
+| `npm run serve` | Preview production build locally |
+| `npm run slidev` | Launch Slidev (if `--addon-slidev` enabled) |
+| `npm run typecheck` | Run TypeScript type checking |
+
+## Requirements
+
+- **Node.js** >= 20.0
+- **Package Manager** - npm, yarn, pnpm, or bun

package/docs/install.mdx

@@ -0,0 +1,199 @@
+---
+sidebar_position: 1.1
+sidebar_custom_props:
+  section: "Setup"
+  section_position: 1
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Installation
+
+No installation required! Use `npx` to run the latest version:
+
+```bash
+npx @sp-days-framework/create-sp-days
+```
+
+Or install globally if you create courses frequently:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm install -g @sp-days-framework/create-sp-days
+    ```
+  </TabItem>
+  <TabItem value="yarn" label="Yarn">
+    ```bash
+    yarn global add @sp-days-framework/create-sp-days
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm add -g @sp-days-framework/create-sp-days
+    ```
+  </TabItem>
+  <TabItem value="bun" label="Bun">
+    ```bash
+    bun add -g @sp-days-framework/create-sp-days
+    ```
+  </TabItem>
+</Tabs>
+
+Then run the tool:
+
+```bash
+create-sp-days my-course
+```
+
+## Usage Examples
+
+### Interactive Setup (Recommended)
+
+The easiest way to get started is interactive mode:
+
+```bash
+npx @sp-days-framework/create-sp-days
+```
+
+**What you'll be asked:**
+
+1. **Site name** - Directory name (e.g., `docs`)
+2. **Project name** - Package name (defaults to site name)
+3. **GitHub organization** - Your org (defaults to `helse-sorost`)
+4. **Repository name** - Repo name (defaults to project name)
+5. **Site title** - Display title (e.g., `Docker Fundamentals`)
+6. **Tagline** - Brief description (e.g., `Master containerization`)
+7. **Add Slidev?** - Enable presentations (yes/no)
+8. **Add Resources?** - Enable documentation (yes/no)
+
+:::tip[Auto-detection]
+The package manager is auto-detected from your system. You can override it by selecting a different option.
+:::
+
+### Minimal Setup
+
+Create a basic course with defaults:
+
+```bash
+npx @sp-days-framework/create-sp-days my-course
+```
+
+This creates a project with:
+
+- Directory: `my-course`
+- Title: `SP Days Template`
+- Tagline: `Empowered by Docusaurus and Slidev`
+- Organization: `helse-sorost`
+- No addons
+
+### Skip Dependency Installation
+
+Create the structure without installing dependencies:
+
+```bash
+npx @sp-days-framework/create-sp-days my-course --skip-install
+cd my-course
+npm install
+```
+
+Useful when:
+
+- You want to review the structure first
+- You need to configure proxies or registries
+- You're working offline
+
+## Understanding Addons
+
+### Base Template Features
+
+Every course includes:
+
+```json title="package.json" {3-5}
+{
+  "dependencies": {
+    "@docusaurus/core": "3.9.2",
+    "@sp-days-framework/docusaurus-plugin-interactive-tasks": "^1.0.0",
+    "@sp-days-framework/docusaurus-frontpage-collection": "^1.0.0"
+  }
+}
+```
+
+**Pre-configured:**
+
+- Docusaurus preset-classic
+- Interactive task system
+- Frontpage component library
+- TypeScript support
+- SASS/SCSS styling
+- Mermaid diagram support
+
+### Slidev Addon (`--addon-slidev`)
+
+Adds presentation capabilities:
+
+```json title="package.json" {6-7}
+{
+  "dependencies": {
+    "@docusaurus/core": "3.9.2",
+    "@sp-days-framework/docusaurus-plugin-interactive-tasks": "^1.0.0",
+    "@sp-days-framework/docusaurus-frontpage-collection": "^1.0.0",
+    "@sp-days-framework/docusaurus-plugin-slidev": "^1.0.0",
+    "@sp-days-framework/slidev-theme-sykehuspartner": "^1.0.0"
+  }
+}
+```
+
+**Adds:**
+
+- `/slidev` directory with example presentations
+- Slidev plugin configuration
+- `npm run slidev` script
+- Presentation overview page
+
+**When to use:**
+
+- Course includes lectures or presentations
+- You want slide-based content alongside documentation
+- You need speaker notes and presenter mode
+
+### Resources Addon (`--addon-resources`)
+
+Adds comprehensive documentation:
+
+**Adds:**
+
+- `/resources` directory structure
+- Component usage guides
+- Setup and configuration examples
+- Best practices documentation
+
+**When to use:**
+
+- Large courses needing separate documentation
+- Multiple instructors needing reference materials
+- Courses with complex component usage
+
+### Package Documentation (`--include-package-docs`)
+
+Adds comprehensive developer documentation:
+
+**Adds:**
+
+- Documentation instances for all installed plugins
+- API references and developer guides
+- "Plugin Docs" dropdown in navbar
+- Routes like `/package-docs/interactive-tasks`
+
+**When to use:**
+
+- Package development and testing
+- Easier access to plugin documentation
+- Demoing framework capabilities
+
+:::warning Production Considerations
+Starting from version 1.1.0, all `@sp-days-framework` packages include their documentation as pre-made Docusaurus MDX files. While useful for development, this feature adds unnecessary dependencies to production builds. Consider removing it before deploying (see generated README for instructions).
+
+**Important:** Enabling package documentation automatically installs the Slidev addon because package docs include Slidev theme documentation.
+:::

package/docs/sidebar-sections.mdx

@@ -0,0 +1,268 @@
+---
+sidebar_position: 2
+sidebar_label: "Sidebar Sections"
+sidebar_custom_props:
+  section: "Components"
+  section_position: 2
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Dynamic Sidebar Sections
+
+Group related documentation pages under visual separators in the sidebar without creating static category structures.
+
+## Overview
+
+The dynamic sidebar sections feature allows you to organize documentation by adding custom section separators that group related pages together. Pages are grouped based on a `section` property in their frontmatter, and sections appear with visual separators in the sidebar.
+
+**Benefits:**
+- Keep files in a flat structure (no nested folders required)
+- Flexible grouping without static `_category_.json` files
+- Multiple sections per documentation instance
+- Visual separation for better navigation
+- Maintains alphabetical or position-based ordering within sections
+
+## Setup
+
+The `sidebarSections.js` file is included by default in projects created with `create-sp-days`. Simply configure it in your Docusaurus config:
+
+### Configure Docusaurus
+
+Add the `sidebarItemsGenerator` option to your docs plugin configuration:
+
+```typescript title="docusaurus.config.ts"
+{
+  plugins: [
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        id: "resources",
+        path: "resources",
+        routeBasePath: "resources",
+        // highlight-next-line
+        sidebarItemsGenerator: require('./sidebarSections'),
+      },
+    ],
+  ],
+}
+```
+
+## Usage
+
+### Add Section to Pages
+
+In the frontmatter of any documentation page, add the `sidebar_custom_props.section` field:
+
+```mdx title="api-reference.mdx"
+---
+sidebar_label: "API Reference"
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 2
+---
+
+# API Reference Template
+
+Your content here...
+```
+
+```mdx title="quick-start.mdx"
+---
+sidebar_label: "Quick Start"
+sidebar_custom_props:
+  section: "Getting Started"
+  section_position: 1
+---
+
+# Quick Start Guide
+
+Your content here...
+```
+
+The `section_position` field is optional and controls the order in which sections appear. Sections without a position will be sorted alphabetically after positioned sections.
+
+### Add Section to Categories
+
+You can also apply sections to entire directories (categories) using `_category_.yml` or `_category_.json` files:
+
+<Tabs>
+  <TabItem value="yaml" label="YAML" default>
+    ```yaml title="docs/layouts/_category_.yml"
+    position: 3
+    label: "Layouts"
+    customProps:
+      section: "Components"
+      section_position: 2
+    ```
+  </TabItem>
+  <TabItem value="json" label="JSON">
+    ```json title="docs/templates/_category_.json"
+    {
+      "position": 2,
+      "label": "Templates",
+      "customProps": {
+        "section": "Reference",
+        "section_position": 3
+      }
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+This groups the entire category under the specified section, allowing you to organize both individual pages and directories together.
+
+### Pages Without Sections
+
+Pages without a `section` property will appear at the top of the sidebar in their natural order:
+
+```mdx title="introduction.mdx"
+---
+sidebar_label: "Introduction"
+sidebar_position: 1
+---
+
+# Introduction
+
+This page appears before any sections.
+```
+
+## Example Sidebar Structure
+
+With the following pages:
+
+- `introduction.mdx` (no section, `sidebar_position: 1`)
+- `best-practices.mdx` (no section, `sidebar_position: 2`)
+- `quick-start.mdx` (`section: "Getting Started"`)
+- `installation.mdx` (`section: "Getting Started"`)
+- `api-reference.mdx` (`section: "Templates"`)
+- `cheat-sheet.mdx` (`section: "Templates"`)
+
+The sidebar will display as:
+
+```
+Introduction
+Best Practices
+───── Getting Started ─────
+Quick Start
+Installation
+───── Templates ─────
+API Reference
+Cheat Sheet
+```
+
+## Multiple Sections
+
+You can create as many sections as needed. Each unique `section` value creates a new separator:
+
+```mdx
+sidebar_custom_props:
+  section: "Advanced Topics"
+```
+
+```mdx
+sidebar_custom_props:
+  section: "Reference"
+```
+
+```mdx
+sidebar_custom_props:
+  section: "Troubleshooting"
+```
+
+## Ordering
+
+### Within Sections
+
+Use `sidebar_position` to control the order of pages within a section:
+
+```mdx
+---
+sidebar_label: "Basic Usage"
+sidebar_position: 1
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 2
+---
+```
+
+```mdx
+---
+sidebar_label: "Advanced Usage"
+sidebar_position: 2
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 2
+---
+```
+
+### Section Order
+
+Use `section_position` to control the order in which sections appear:
+
+- Sections with `section_position: 1` appear first
+- Sections with `section_position: 2` appear second, etc.
+- Sections without `section_position` are sorted alphabetically and appear last
+
+**Important:** All pages within the same section must use the same `section_position` value (or all omit it). Mixing different `section_position` values within a section will throw a validation error.
+
+```mdx title="✅ Correct - Same section_position for all pages in section"
+# Page 1
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 2
+
+# Page 2  
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 2
+```
+
+```mdx title="❌ Incorrect - Different section_position values"
+# Page 1
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 2
+
+# Page 2
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 3  # ❌ Error!
+```
+
+:::tip
+You only need to add `section_position` to one page in each section - if omitted on other pages in the same section, they'll inherit the behavior. However, adding it to all pages makes the intent clearer.
+:::
+
+:::warning Limitations
+- Use only **one** `section` value per page
+- All pages in a section must have the same `section_position` (or none)
+:::
+
+## Styling Customization
+
+The separator styling uses CSS custom properties for theming:
+
+- `--ifm-color-emphasis-600` - Text color
+- `--ifm-color-emphasis-300` - Border color
+
+To customize the separator appearance, edit the inline styles in `sidebarSections.js`:
+
+```javascript title="sidebarSections.js"
+value: `<div style="margin: 1rem 0 0.5rem; padding: 0.25rem 0; font-size: 0.75rem; ...">${sectionName}</div>`,
+```
+
+You can also target the generated class names with CSS:
+
+```css title="custom.css"
+[class*="sidebar-section-"] {
+  /* Custom styles for all section separators */
+}
+
+.sidebar-section-templates {
+  /* Styles specific to "Templates" section */
+}
+```
+
+Class names are auto-generated from section names: `"Templates"` → `sidebar-section-templates`, `"Getting Started"` → `sidebar-section-getting-started`.