# 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

#### 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)

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) |
| `--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 | - |
| `--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