---
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.
:::