@sp-days-framework/create-sp-days 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Helse Sør-Øst
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,318 @@
+# Create Sykehuspartner Days Template
+
+Scaffolding tool for creating SP-Days course websites built on Docusaurus and Slidev.
+
+## Quick Start
+
+```bash
+npx @sp-days-framework/create-sp-days example-directory
+```
+
+This will create a new SP-Days course website with:
+
+- Docusaurus-based course structure
+- Interactive task system
+- Frontpage components collection
+- TypeScript configuration
+- Pre-configured theme and styling
+
+## Features
+
+### Base Template (Always Included)
+
+The base `page-course` template includes:
+
+- **Docusaurus Core**: Latest Docusaurus 3.x with preset-classic
+- **Interactive Tasks**: `@sp-days-framework/docusaurus-plugin-interactive-tasks` for hands-on learning
+- **Frontpage Components**: `@sp-days-framework/docusaurus-frontpage-collection` for beautiful landing pages
+- **Course Structure**: Pre-configured `/course` directory for content
+- **TypeScript**: Full TypeScript support out of the box
+- **SASS Support**: Custom styling with SASS/SCSS
+- **Mermaid Diagrams**: Built-in diagram support
+
+### Optional Addons
+
+#### Slidev Integration (`--addon-slidev`)
+
+Adds presentation capabilities:
+
+- `@sp-days-framework/docusaurus-plugin-slidev`: Seamless Slidev integration
+- `@sp-days-framework/slidev-theme-sykehuspartner`: Custom Slidev theme
+- Example presentations in `/slidev` directory
+- `npm run slidev` command for presentation mode
+
+#### Resources Page (`--addon-resources`)
+
+Adds comprehensive documentation:
+
+- Separate `/resources` documentation instance
+- Component usage guides
+- Setup and configuration examples
+- Best practices documentation
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+Run without arguments for an interactive setup:
+
+```bash
+npx @sp-days-framework/create-sp-days
+```
+
+You'll be prompted for:
+
+1. Site name (directory name)
+2. Project name
+3. GitHub organization
+4. Repository name
+5. Site title
+6. Site tagline
+7. Slidev integration (yes/no)
+8. Resources page (yes/no)
+9. Package manager selection
+
+### CLI Mode
+
+Provide all options via command line flags:
+
+```bash
+npx @sp-days-framework/create-sp-days my-course \
+  --name "my-course" \
+  --org "my-organization" \
+  --repo "my-course-repo" \
+  --title "Advanced Docker Course" \
+  --tagline "Master containerization in 3 days" \
+  --addon-slidev \
+  --addon-resources \
+  --package-manager npm
+```
+
+## CLI Options
+
+| Flag | Alias | Description | Default |
+|------|-------|-------------|---------|
+| `--name <name>` | `-n` | Project name | Directory name |
+| `--org <organization>` | | GitHub organization | `helse-sorost` |
+| `--repo <repository>` | | Repository name | Project name |
+| `--title <title>` | | Site title | `SP Days Template` |
+| `--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) |
+| `--package-manager <pm>` | `-p` | Package manager (npm/yarn/pnpm/bun) | Auto-detected |
+| `--skip-install` | `-s` | Skip dependency installation | `false` |
+| `--help` | `-h` | Display help | - |
+| `--version` | `-v` | Display version | - |
+
+## Examples
+
+### Minimal Setup
+
+Create a basic course without addons:
+
+```bash
+npx @sp-days-framework/create-sp-days my-course
+```
+
+### With All Features
+
+Create a fully-featured course with presentations and resources:
+
+```bash
+npx @sp-days-framework/create-sp-days docker-course \
+  --addon-slidev \
+  --addon-resources \
+  --title "Docker Fundamentals" \
+  --tagline "Learn containerization from scratch"
+```
+
+### Custom Organization
+
+Set up for a specific GitHub organization:
+
+```bash
+npx @sp-days-framework/create-sp-days kubernetes-101 \
+  --org "acme-corp" \
+  --repo "k8s-training" \
+  --title "Kubernetes 101" \
+  --addon-slidev
+```
+
+### Skip Installation
+
+Create the structure without installing dependencies:
+
+```bash
+npx @sp-days-framework/create-sp-days my-course --skip-install
+cd my-course
+npm install
+```
+
+## What Gets Created
+
+### Directory Structure
+
+```
+my-course/
+├── course/                 # Course content (MDX files)
+│   └── index.mdx          # Course overview
+├── src/
+│   ├── css/
+│   │   └── sp-days-theme.scss
+│   └── pages/
+│       └── index.mdx      # Landing page
+├── static/
+│   └── img/               # Logos and images
+├── docusaurus.config.ts   # Main configuration
+├── package.json           # Dependencies and scripts
+├── tsconfig.json          # TypeScript config
+└── README.md              # Getting started guide
+```
+
+With `--addon-slidev`:
+
+```
+├── slidev/                # Slidev presentations
+│   ├── creating-your-first-slidev.md
+│   └── slidev-theme-sykehuspartner.md
+```
+
+With `--addon-resources`:
+
+```
+├── resources/             # Additional documentation
+│   ├── frontpage-collection/
+│   ├── interactive-tasks/
+│   ├── slidev-integration/
+│   └── sykehuspartner-theme/
+```
+
+### Template Processing
+
+The tool automatically processes template variables:
+
+### Configuration Variables
+
+Variables replaced in template files using simple string replacement:
+
+```typescript
+// In docusaurus.config.ts
+const organizationName = "<%= organizationName %>";
+const projectName = "<%= projectName %>";
+const gitRepositoryUrl = "<%= gitRepositoryUrl %>";
+const title = "<%= title %>";
+const tagline = "<%= tagline %>";
+```
+
+These placeholders are replaced with actual values during installation.
+
+### Conditional Sections
+
+Sections marked with `// CONDITIONAL: addon-name (START/END)` are automatically removed if the addon is not selected:
+
+```typescript
+// CONDITIONAL: addon-slidev (START)
+"@sp-days-framework/docusaurus-plugin-slidev",
+// CONDITIONAL: addon-slidev (END)
+```
+
+## Available Commands
+
+After creation, run these commands in your project:
+
+```bash
+npm start           # Start development server
+npm run build       # Build for production
+npm run serve       # Serve production build
+npm run slidev      # Launch Slidev (if addon installed)
+npm run typecheck   # Run TypeScript checks
+```
+
+## Requirements
+
+- **Node.js**: >= 20.0
+- **Package Manager**: npm, yarn, pnpm, or bun
+
+## Development
+
+### Building the Package
+
+```bash
+# Clone the repository
+git clone https://github.com/helse-sorost/sp-days-framework
+cd sp-days-framework/create-sp-days
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+```
+
+### Testing Locally
+
+There are several ways to test the package locally:
+
+#### Option 1: Using npm link (Recommended for development)
+
+```bash
+# From the create-sp-days directory
+npm link
+
+# Test in a different directory
+cd /tmp
+create-sp-days test-site
+
+# Or using npx
+npx create-sp-days test-site
+
+# When done testing, unlink
+cd /workspaces/sp-days-framework/create-sp-days
+npm unlink -g
+```
+
+#### Option 2: Install from tarball
+
+```bash
+# Create the tarball
+cd /workspaces/sp-days-framework/create-sp-days
+npm pack
+
+# Install globally from tarball
+npm install -g ./sp-days-framework-create-sp-days-1.0.0.tgz
+
+# Test it
+cd /tmp
+create-sp-days test-site
+
+# Uninstall when done
+npm uninstall -g @sp-days-framework/create-sp-days
+```
+
+#### Option 3: Install locally in test directory
+
+```bash
+# Create and navigate to test directory
+mkdir -p /tmp/test-npm
+cd /tmp/test-npm
+
+# Install from tarball
+npm install /workspaces/sp-days-framework/create-sp-days/sp-days-framework-create-sp-days-1.0.0.tgz
+
+# Run it
+npx @sp-days-framework/create-sp-days test-site
+```
+
+## Troubleshooting
+
+### "Exec format error" when using npx with tarball
+
+You cannot execute a `.tgz` file directly with npx. Use one of the methods above instead:
+
+- Install globally with `npm install -g ./package.tgz` then run the command
+- Install locally with `npm install ./package.tgz` then use `npx @sp-days-framework/create-sp-days`
+- Use `npm link` for development testing
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ */
+
+// @ts-check
+
+import path from "path";
+import { createRequire } from "module";
+import { logger } from "@docusaurus/logger";
+import semver from "semver";
+import { program } from "commander";
+
+const packageJson = /** @type {import("../package.json")} */ (
+  createRequire(import.meta.url)("../package.json")
+);
+const requiredVersion = packageJson.engines.node;
+
+if (!semver.satisfies(process.version, requiredVersion)) {
+  logger.error("Minimum Node.js version not met :(");
+  logger.info`You are using Node.js number=${process.version}, Requirement: Node.js number=${requiredVersion}.`;
+  process.exit(1);
+}
+
+program.version(packageJson.version);
+
+program
+  .arguments("[siteName] [rootDir]")
+  .option("-n, --name <name>", "Project name (defaults to directory name)")
+  .option(
+    "--org <organization>",
+    "GitHub organization (defaults to helse-sorost)"
+  )
+  .option("--repo <repository>", "Repository name (defaults to project name)")
+  .option("--title <title>", "Site title (defaults to SP Days Template)")
+  .option(
+    "--tagline <tagline>",
+    "Site tagline (defaults to Empowered by Docusaurus and Slidev)"
+  )
+  .option("--addon-slidev", "Add Slidev integration addon")
+  .option("--addon-resources", "Add Resources page addon")
+  .option(
+    "-p, --package-manager <manager>",
+    "The package manager used to install dependencies. One of yarn, npm, pnpm, and bun."
+  )
+  .option(
+    "-s, --skip-install",
+    "Do not run package manager immediately after scaffolding"
+  )
+  .description("Initialize SP-Days course website.")
+  .action((siteName, rootDir, options) => {
+    // Extract only the CLI option VALUES, avoiding commander methods
+    const cliOptions = {
+      name: typeof options.name === "string" ? options.name : undefined,
+      org: typeof options.org === "string" ? options.org : undefined,
+      repo: typeof options.repo === "string" ? options.repo : undefined,
+      title: typeof options.title === "string" ? options.title : undefined,
+      tagline:
+        typeof options.tagline === "string" ? options.tagline : undefined,
+      addonSlidev: options.addonSlidev === true ? true : undefined,
+      addonResources: options.addonResources === true ? true : undefined,
+      packageManager:
+        typeof options.packageManager === "string"
+          ? options.packageManager
+          : undefined,
+      skipInstall: options.skipInstall === true ? true : undefined,
+    };
+
+    return import("../lib/index.js").then(({ default: init }) =>
+      init(path.resolve(rootDir ?? "."), siteName, cliOptions)
+    );
+  });
+
+program.parse(process.argv);
+
+if (!process.argv.slice(1).length) {
+  program.outputHelp();
+}
+
+process.on("unhandledRejection", (err) => {
+  logger.error(err);
+  process.exit(1);
+});

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+type CLIOptions = {
+    name?: string;
+    org?: string;
+    repo?: string;
+    title?: string;
+    tagline?: string;
+    addonSlidev?: boolean;
+    addonResources?: boolean;
+    packageManager?: PackageManager;
+    skipInstall?: boolean;
+};
+declare const lockfileNames: {
+    npm: string;
+    yarn: string;
+    pnpm: string;
+    bun: string;
+};
+type PackageManager = keyof typeof lockfileNames;
+export default function init(rootDir: string, reqName?: string, cliOptions?: CLIOptions): Promise<void>;
+export {};