Create Sykehuspartner Days Template

Scaffolding tool for creating SP-Days course websites built on Docusaurus and Slidev.

Quick Start

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:

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:

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:

npx @sp-days-framework/create-sp-days my-course

With All Features

Create a fully-featured course with presentations and resources:

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:

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:

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:

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

// CONDITIONAL: addon-slidev (START)
"@sp-days-framework/docusaurus-plugin-slidev",
// CONDITIONAL: addon-slidev (END)

Available Commands

After creation, run these commands in your project:

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

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

# 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

# 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

# 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