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

package/README.md

@@ -50,6 +50,19 @@ Adds comprehensive documentation:
 - Setup and configuration examples
 - Best practices documentation
 
+#### Plugin Documentation (`--include-package-docs`)
+
+Adds developer documentation for installed plugins:
+
+- Separate documentation instances for each plugin
+- Developer guides and API references
+- Accessible via "Plugin Docs" dropdown in navbar
+- Routes: `/package-docs/interactive-tasks`, etc.
+
+**Note:** Starting from version 1.1.0, all `@sp-days-framework` packages include their documentation as pre-made Docusaurus-formatted MDX files. This feature is primarily useful during package development or for easier access to documentation, but it does add unnecessary dependencies for production builds.
+
+**Important:** When package documentation is enabled, the Slidev addon is automatically installed (even if not explicitly requested) because the package docs include Slidev theme documentation.
+
 ## Usage
 
 ### Interactive Mode (Recommended)
@@ -99,6 +112,7 @@ npx @sp-days-framework/create-sp-days my-course \
 | `--tagline <tagline>` | | Site tagline | `Empowered by Docusaurus and Slidev` |
 | `--addon-slidev` | | Add Slidev integration | `false` (CLI), prompted (interactive) |
 | `--addon-resources` | | Add Resources page | `false` (CLI), prompted (interactive) |
+| `--include-package-docs` | | Include plugin documentation | `false` (CLI), prompted (interactive) |
 | `--package-manager <pm>` | `-p` | Package manager (npm/yarn/pnpm/bun) | Auto-detected |
 | `--skip-install` | `-s` | Skip dependency installation | `false` |
 | `--help` | `-h` | Display help | - |

package/bin/index.js

@@ -42,6 +42,7 @@ program
   )
   .option("--addon-slidev", "Add Slidev integration addon")
   .option("--addon-resources", "Add Resources page addon")
+  .option("--include-package-docs", "Include package documentation instances")
   .option(
     "-p, --package-manager <manager>",
     "The package manager used to install dependencies. One of yarn, npm, pnpm, and bun."
@@ -62,6 +63,7 @@ program
         typeof options.tagline === "string" ? options.tagline : undefined,
       addonSlidev: options.addonSlidev === true ? true : undefined,
       addonResources: options.addonResources === true ? true : undefined,
+      includePackageDocs: options.includePackageDocs === true ? true : undefined,
       packageManager:
         typeof options.packageManager === "string"
           ? options.packageManager

package/docs/advanced-config.mdx

@@ -0,0 +1,412 @@
+---
+sidebar_position: 1.2
+sidebar_custom_props:
+  section: "Setup"
+  section_position: 1
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Advanced Configuration
+
+## CLI Reference
+
+### Command Syntax
+
+```bash
+create-sp-days [directory] [options]
+```
+
+or
+
+```bash
+npx @sp-days-framework/create-sp-days [directory] [options]
+```
+
+### All CLI Options
+
+| Flag | Alias | Type | Default | Description |
+|------|-------|------|---------|-------------|
+| `[directory]` | - | `string` | - | Target directory name (required in CLI mode) |
+| `--name <name>` | `-n` | `string` | Directory name | Project name for package.json |
+| `--org <organization>` | - | `string` | `helse-sorost` | GitHub organization name |
+| `--repo <repository>` | - | `string` | Project name | GitHub repository name |
+| `--title <title>` | - | `string` | `SP Days Template` | Site title displayed in header |
+| `--tagline <tagline>` | - | `string` | `Empowered by Docusaurus and Slidev` | Site tagline/subtitle |
+| `--addon-slidev` | - | `boolean` | `false` | Enable Slidev presentation integration |
+| `--addon-resources` | - | `boolean` | `false` | Enable Resources documentation |
+| `--include-package-docs` | - | `boolean` | `false` | Include package documentation (auto-enables Slidev) |
+| `--package-manager <pm>` | `-p` | `string` | Auto-detected | Package manager: npm, yarn, pnpm, or bun |
+| `--skip-install` | `-s` | `boolean` | `false` | Skip dependency installation |
+| `--help` | `-h` | - | - | Display help information |
+| `--version` | `-v` | - | - | Display version number |
+
+### Interactive vs CLI Mode
+
+**Interactive Mode:**
+
+```bash
+npx @sp-days-framework/create-sp-days
+```
+
+- Prompts for all options
+- Provides suggestions and defaults
+- Validates input in real-time
+- Best for first-time users
+
+**CLI Mode:**
+
+```bash
+npx @sp-days-framework/create-sp-days my-course --title "My Course"
+```
+
+- Specify options as flags
+- Non-interactive (suitable for scripts)
+- Uses defaults for unspecified options
+- Best for automation
+
+:::tip
+In CLI mode, any missing required options will be prompted interactively.
+:::
+
+## Usage Patterns
+
+### Complete Course Setup
+
+Create a production-ready course with all features:
+
+```bash
+npx @sp-days-framework/create-sp-days kubernetes-course \
+  --name "kubernetes-course" \
+  --org "my-company" \
+  --repo "k8s-training-2024" \
+  --title "Kubernetes Essentials" \
+  --tagline "From Zero to Production in 5 Days" \
+  --addon-slidev \
+  --addon-resources \
+  --package-manager npm
+```
+
+**Generated structure:**
+
+- Directory: `kubernetes-course/`
+- Package: `kubernetes-course`
+- URL: `https://my-company.github.io/k8s-training-2024/`
+- Includes: Slidev + Resources
+- Dependencies: Installed with npm
+
+## Project Structure Examples
+
+### Base Template
+
+```
+docker-course/
+├── course/                 # Your course content
+│   ├── index.mdx          # Course overview
+│   ├── module-1/
+│   └── module-2/
+├── src/
+│   ├── css/
+│   │   └── sp-days-theme.scss
+│   └── pages/
+│       └── index.mdx      # Landing page
+├── static/
+│   └── img/               # Images and assets
+├── docusaurus.config.ts   # Main configuration
+└── package.json           # Dependencies and scripts
+```
+
+### With `--addon-slidev`
+
+```
+├── slidev/                # Presentations
+│   └── introduction.md
+```
+
+### With `--addon-resources`
+
+```
+├── resources/             # Documentation
+│   └── frontpage-collection/
+```
+
+## How It Works
+
+### Template Processing
+
+The scaffolding tool processes template files in several steps:
+
+1. **Variable Replacement** - Substitutes placeholders with user-provided values
+2. **Conditional Sections** - Includes/excludes code blocks based on selected addons
+3. **File Generation** - Creates final project structure
+4. **Dependency Installation** - Installs packages (unless `--skip-install` is used)
+
+### Variable Replacement
+
+Template files use placeholder variables that are replaced during project creation:
+
+**Available variables:**
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `<%= organizationName %>` | GitHub organization | `helse-sorost` |
+| `<%= projectName %>` | Project/package name | `docker-course` |
+| `<%= gitRepositoryUrl %>` | Full repository URL | `https://github.com/...` |
+| `<%= title %>` | Site title | `Docker Fundamentals` |
+| `<%= tagline %>` | Site tagline | `Master containerization` |
+
+**Example transformation:**
+
+Before (template):
+
+```typescript title="docusaurus.config.ts"
+const config: Config = {
+  title: "<%= title %>",
+  tagline: "<%= tagline %>",
+  url: "https://<%= organizationName %>.github.io",
+  baseUrl: "/<%= projectName %>/",
+};
+```
+
+After (processed):
+
+```typescript title="docusaurus.config.ts"
+const config: Config = {
+  title: "Docker Fundamentals",
+  tagline: "Master containerization",
+  url: "https://acme-corp.github.io",
+  baseUrl: "/docker-course/",
+};
+```
+
+### Conditional Sections
+
+Addon-specific code blocks are automatically included or excluded:
+
+**Marker format:**
+
+```typescript
+// CONDITIONAL: addon-name (START)
+...code to include if addon is enabled...
+// CONDITIONAL: addon-name (END)
+```
+
+**Example - Slidev addon:**
+
+Template file:
+
+```typescript title="docusaurus.config.ts"
+plugins: [
+  "@sp-days-framework/docusaurus-plugin-interactive-tasks",
+  // CONDITIONAL: addon-slidev (START)
+  "@sp-days-framework/docusaurus-plugin-slidev",
+  // CONDITIONAL: addon-slidev (END)
+]
+```
+
+With `--addon-slidev`:
+
+```typescript
+plugins: [
+  "@sp-days-framework/docusaurus-plugin-interactive-tasks",
+  "@sp-days-framework/docusaurus-plugin-slidev",
+]
+```
+
+Without `--addon-slidev`:
+
+```typescript
+plugins: [
+  "@sp-days-framework/docusaurus-plugin-interactive-tasks",
+]
+```
+
+## Package Documentation Feature
+
+### Overview
+
+Starting from version 1.1.0, all `@sp-days-framework` packages include their documentation as pre-made Docusaurus-formatted MDX files. The `--include-package-docs` flag enables this feature, making plugin documentation accessible directly within your course website.
+
+### How It Works
+
+Each `@sp-days-framework` package includes a `publish-package-docs.js` file that exports documentation configuration:
+
+```javascript title="publish-package-docs.js"
+module.exports = {
+  id: "interactive-tasks-docs",
+  path: require("path").join(__dirname, "docs"),
+  routeBasePath: "package-docs/interactive-tasks",
+};
+```
+
+This configuration is consumed by Docusaurus as a separate documentation instance:
+
+```typescript title="docusaurus.config.ts"
+plugins: [
+  // Interactive Tasks Plugin Documentation
+  [
+    "@docusaurus/plugin-content-docs",
+    require("@sp-days-framework/docusaurus-plugin-interactive-tasks/publish-package-docs"),
+  ],
+  // Additional package docs...
+]
+```
+
+The navbar includes a dropdown for easy access:
+
+```typescript title="docusaurus.config.ts"
+navbar: {
+  items: [
+    {
+      type: "dropdown",
+      label: "Plugin Docs",
+      position: "left",
+      items: [
+        { to: "/package-docs/create-sp-days", label: "Create SP Days" },
+        { to: "/package-docs/frontpage-collection", label: "Frontpage Collection" },
+        { to: "/package-docs/interactive-tasks", label: "Interactive Tasks" },
+        { to: "/package-docs/slidev-integration", label: "Slidev Integration" },
+        { to: "/package-docs/sykehuspartner-theme", label: "Sykehuspartner Theme" },
+      ],
+    },
+  ],
+}
+```
+
+### Automatic Slidev Installation
+
+When `--include-package-docs` is enabled, the Slidev addon is automatically installed, even if you didn't explicitly request it with `--addon-slidev`. This is because the package documentation includes documentation for the Slidev theme (`@sp-days-framework/slidev-theme-sykehuspartner`).
+
+**What gets installed:**
+
+- `/slidev` directory with example presentations
+- `@sp-days-framework/docusaurus-plugin-slidev` package
+- `@sp-days-framework/slidev-theme-sykehuspartner` package
+- `npm run slidev` script
+
+### Use Cases
+
+**Recommended for:**
+
+- Package development and testing
+- Framework demonstration sites
+- Local documentation access during development
+- Exploring plugin capabilities
+
+**Not recommended for:**
+
+- Production course websites
+- Deployed training sites
+- Minimal dependency requirements
+
+The feature adds approximately 5 additional packages to your `node_modules` and increases build time slightly.
+
+### Removing Package Documentation
+
+If you initially enabled package documentation but want to remove it:
+
+1. **Remove package documentation plugins** from `docusaurus.config.ts`:
+
+   ```typescript
+   // Remove these plugin entries:
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        sidebarItemsGenerator: require('./sidebarSections'),
+        ...require("@sp-days-framework/docusaurus-plugin-interactive-tasks/publish-package-docs"),
+      },
+    ],
+    // Slidev Plugin Documentation 
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        sidebarItemsGenerator: require('./sidebarSections'),
+        ...require("@sp-days-framework/docusaurus-plugin-slidev/publish-package-docs"),
+      },
+    ],
+    // Frontpage Collection Documentation
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        sidebarItemsGenerator: require('./sidebarSections'),
+        ...require("@sp-days-framework/docusaurus-frontpage-collection/publish-package-docs"),
+      },
+    ],
+    // Sykehuspartner Slidev Theme Documentation
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        sidebarItemsGenerator: require('./sidebarSections'),
+        ...require("@sp-days-framework/slidev-theme-sykehuspartner/publish-package-docs"),
+      },
+    ],
+    // Create SP Days Documentation
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        sidebarItemsGenerator: require('./sidebarSections'),
+        ...require("@sp-days-framework/create-sp-days/publish-package-docs"),
+      },
+    ],
+   ```
+
+2. **Remove the Plugin Docs dropdown** from the navbar in `docusaurus.config.ts`:
+
+   ```typescript
+   // Remove this navbar item:
+    {
+      type: "dropdown",
+      label: "Plugin Docs",
+      position: "left",
+      items: [
+        {
+          to: "/package-docs/create-sp-days",
+          label: "Create SP Days",
+          className: "title-logo-navbar-sp-days-plugin",
+        },
+        {
+          to: "/package-docs/frontpage-collection",
+          label: "Frontpage Collection",
+          className: "title-logo-navbar-docusaurus",
+        },
+        {
+          to: "/package-docs/interactive-tasks",
+          label: "Interactive Tasks",
+          className: "title-logo-navbar-docusaurus",
+        },
+        {
+          to: "/package-docs/slidev-integration",
+          label: "Slidev Integration",
+          className: "title-logo-navbar-docusaurus",
+        },
+        {
+          to: "/package-docs/terminal-codeblock",
+          label: "Terminal Codeblock",
+          className: "title-logo-navbar-docusaurus",
+        },
+        {
+          to: "/package-docs/sykehuspartner-theme",
+          label: "Sykehuspartner Theme",
+          className: "title-logo-navbar-slidev",
+        },
+      ],
+    },
+   ```
+
+3. **Remove the package dependency** from `package.json`:
+
+   ```json
+   // Remove this line from dependencies:
+   "@sp-days-framework/create-sp-days": "^1.0.4",
+   ```
+
+4. **Reinstall dependencies**:
+
+   ```bash
+   npm install
+   ```
+
+:::tip Keep Slidev?
+If you want to keep the Slidev functionality but remove package docs, you don't need to remove the Slidev-related packages. Just remove the package documentation plugins and navbar items.
+:::

package/docs/changelog.mdx

@@ -0,0 +1,129 @@
+---
+sidebar_position: 3
+sidebar_label: "Change Logs"
+toc_max_heading_level: 2
+sidebar_custom_props:
+  section: "Releases"
+  section_position: 3
+---
+
+# Changelog
+
+## `@sp-days-framework/create-sp-days`
+
+[![npm version](https://img.shields.io/npm/v/@sp-days-framework/create-sp-days?logo=nodedotjs)](https://www.npmjs.com/package/@sp-days-framework/create-sp-days)
+
+:::note
+All packages within `@sp-days-framework` use the same version number. In some cases, a package might just be "bumped" to match the rest without any functional changes.
+:::
+
+---
+
+## Version 1.1.0-beta2 ![beta](https://img.shields.io/badge/release-beta-yellow)
+
+Terminal plugin integration and documentation refinements
+
+<details>
+<summary><strong>Beta Details</strong> (2025 December 09)</summary>
+
+### New Features
+
+- **Terminal Codeblock Plugin**: Integrated the new `@sp-days-framework/docusaurus-plugin-terminal-codeblock` package
+  - Automatically included in new project scaffolds
+  - Pre-configured for optimal terminal documentation display
+  - Enables realistic command-line examples in course materials
+
+### Improvements
+
+- **Enhanced Documentation Structure**: Updated sidebar positions and added known issues documentation for better navigation
+- **Visual Consistency**: Improved sidebar and navbar logo handling across all generated documentation
+
+</details>
+
+---
+
+## Version 1.1.0-beta1 ![beta](https://img.shields.io/badge/release-beta-yellow)
+
+Get started faster with improved resource templates
+
+<details>
+<summary><strong>Beta Details</strong> (2025 December 08)</summary>
+
+### Improvements
+
+- **Redesigned Resource Templates**: The `addon-resources` option now includes practical, ready-to-use templates
+  - Pre-built pages for API references, FAQs, glossaries, troubleshooting guides, and more
+  - Best practice examples to help you structure your course materials effectively
+  - No more outdated package documentation - just helpful starting points for your content
+  - Faster course setup with less manual work
+
+- **Updated Dependencies**: Templates now include the latest component versions and examples
+
+### Package Documentation
+
+- Documentation is now bundled with the npm package, making it accessible during development and for offline reference
+
+</details>
+
+---
+
+## Version 1.0.4 ![Release](https://img.shields.io/badge/release-production-blue)
+
+Update documentation and dependencies
+
+<details>
+<summary><strong>Details</strong> (2025 December 1)</summary>
+
+### Improvements
+
+- Updated `docusaurus-frontpage-collection` documentation
+- Updated `docusaurus-interactive-task` documentation
+- Updated Docusaurus config file in template to match new `docusaurus-interactive-task` feature
+- Version bump packages used in template
+
+</details>
+
+---
+
+## Version 1.0.3 ![Sync](https://img.shields.io/badge/sync-version--bump-lightgrey)
+
+Update dependencies
+
+<details>
+<summary><strong>Details</strong> (2025 November 27)</summary>
+
+### Improvements
+
+- Version bump packages used in template
+
+</details>
+
+---
+
+## Version 1.0.2 ![Sync](https://img.shields.io/badge/sync-version--bump-lightgrey)
+
+Update dependencies
+
+<details>
+<summary><strong>Details</strong> (2025 November 25)</summary>
+
+### Improvements
+
+- Version bump packages used in template
+
+</details>
+
+---
+
+## Version 1.0.0 ![Release](https://img.shields.io/badge/release-production-blue)
+
+Initial release of the Create SP Days package
+
+<details>
+<summary><strong>Details</strong> (2025 November 24)</summary>
+
+### New Features
+
+- Initial release with scaffolding tool for creating SP Days course websites
+
+</details>