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

package/lib/index.js

@@ -0,0 +1,454 @@
+import fs from "fs-extra";
+import { fileURLToPath } from "url";
+import path from "path";
+import { logger } from "@docusaurus/logger";
+import execa from "execa";
+import prompts from "prompts";
+import supportsColor from "supports-color";
+// Only used in the rare, rare case of running globally installed create +
+// using --skip-install. We need a default name to show the tip text
+const defaultPackageManager = "npm";
+const lockfileNames = {
+    npm: "package-lock.json",
+    yarn: "yarn.lock",
+    pnpm: "pnpm-lock.yaml",
+    bun: "bun.lockb",
+};
+const packageManagers = Object.keys(lockfileNames);
+async function findPackageManagerFromLockFile(rootDir) {
+    for (const packageManager of packageManagers) {
+        const lockFilePath = path.join(rootDir, lockfileNames[packageManager]);
+        if (await fs.pathExists(lockFilePath)) {
+            return packageManager;
+        }
+    }
+    return undefined;
+}
+function findPackageManagerFromUserAgent() {
+    return packageManagers.find((packageManager) => process.env.npm_config_user_agent?.startsWith(packageManager));
+}
+async function askForPackageManagerChoice() {
+    const hasYarn = (await execa.command("yarn --version")).exitCode === 0;
+    const hasPnpm = (await execa.command("pnpm --version")).exitCode === 0;
+    const hasBun = (await execa.command("bun --version")).exitCode === 0;
+    if (!hasYarn && !hasPnpm && !hasBun) {
+        return "npm";
+    }
+    const choices = ["npm", hasYarn && "yarn", hasPnpm && "pnpm", hasBun && "bun"]
+        .filter((p) => Boolean(p))
+        .map((p) => ({ title: p, value: p }));
+    return ((await prompts({
+        type: "select",
+        name: "packageManager",
+        message: "Select a package manager...",
+        choices,
+    }, {
+        onCancel() {
+            logger.info `Falling back to name=${defaultPackageManager}`;
+        },
+    })).packageManager ?? defaultPackageManager);
+}
+async function getPackageManager(dest, { packageManager, skipInstall }) {
+    if (packageManager && !packageManagers.includes(packageManager)) {
+        throw new Error(`Invalid package manager choice ${packageManager}. Must be one of ${packageManagers.join(", ")}`);
+    }
+    return (packageManager ??
+        (await findPackageManagerFromLockFile(dest)) ??
+        findPackageManagerFromUserAgent() ??
+        (skipInstall ? defaultPackageManager : askForPackageManagerChoice()));
+}
+const templatesDir = fileURLToPath(new URL("../templates", import.meta.url));
+async function getSiteName(reqName, rootDir) {
+    async function validateSiteName(siteName) {
+        if (!siteName) {
+            return "A site name is required.";
+        }
+        const dest = path.resolve(rootDir, siteName);
+        if (await fs.pathExists(dest)) {
+            return logger.interpolate `Directory already exists at path=${dest}!`;
+        }
+        return true;
+    }
+    if (reqName) {
+        const res = await validateSiteName(reqName);
+        if (typeof res === "string") {
+            throw new Error(res);
+        }
+        return reqName;
+    }
+    const { siteName } = (await prompts({
+        type: "text",
+        name: "siteName",
+        message: "What should we name your site directory?",
+        initial: "docs",
+        validate: validateSiteName,
+    }, {
+        onCancel() {
+            logger.error("A site name is required.");
+            process.exit(1);
+        },
+    }));
+    return siteName;
+}
+async function getProjectConfig(siteName, cliOptions) {
+    // Get configuration from prompts or CLI options
+    const defaultOrg = "helse-sorost";
+    const defaultRepo = "example-repo";
+    const defaultTitle = "SP Days Template";
+    const defaultTagline = "Empowered by Docusaurus and Slidev";
+    let organizationName;
+    let repositoryName;
+    let title;
+    let tagline;
+    // Check if ANY configuration options were provided via CLI
+    const hasCliConfig = !!(cliOptions.name ||
+        cliOptions.org ||
+        cliOptions.repo ||
+        cliOptions.title ||
+        cliOptions.tagline);
+    if (hasCliConfig) {
+        // Use CLI options with defaults
+        organizationName = cliOptions.org ?? defaultOrg;
+        repositoryName = cliOptions.repo ?? cliOptions.name ?? defaultRepo;
+        title = cliOptions.title ?? defaultTitle;
+        tagline = cliOptions.tagline ?? defaultTagline;
+    }
+    else {
+        // Interactive prompts
+        const answers = await prompts([
+            {
+                type: "text",
+                name: "organizationName",
+                message: "What is your GitHub organization?",
+                initial: defaultOrg,
+            },
+            {
+                type: "text",
+                name: "repositoryName",
+                message: "What is your repository name?",
+                initial: defaultRepo,
+            },
+            {
+                type: "text",
+                name: "title",
+                message: "What is your site title?",
+                initial: defaultTitle,
+            },
+            {
+                type: "text",
+                name: "tagline",
+                message: "What is your site tagline?",
+                initial: defaultTagline,
+            },
+        ], {
+            onCancel() {
+                logger.error("Configuration is required.");
+                process.exit(1);
+            },
+        });
+        // Ensure we have values - use defaults if prompts were somehow bypassed
+        organizationName = answers.organizationName || defaultOrg;
+        repositoryName = answers.repositoryName || defaultRepo;
+        title = answers.title || defaultTitle;
+        tagline = answers.tagline || defaultTagline;
+    }
+    // Get addon selections
+    let addonSlidev;
+    let addonResources;
+    if (hasCliConfig) {
+        // If using CLI mode for config, also use CLI mode for addons (default to false if not specified)
+        addonSlidev = cliOptions.addonSlidev ?? false;
+        addonResources = cliOptions.addonResources ?? false;
+    }
+    else if (cliOptions.addonSlidev !== undefined ||
+        cliOptions.addonResources !== undefined) {
+        // Addon flags provided without config flags
+        addonSlidev = cliOptions.addonSlidev ?? false;
+        addonResources = cliOptions.addonResources ?? false;
+    }
+    else {
+        // Interactive mode - prompt with default yes
+        const addonAnswers = await prompts([
+            {
+                type: "confirm",
+                name: "addonSlidev",
+                message: 'Do you wish to add Slidev Integration?\n  This will create a "./slidev" directory and add the necessary packages.',
+                initial: true,
+            },
+            {
+                type: "confirm",
+                name: "addonResources",
+                message: 'Do you wish to add a Resources page?\n  This will add a "./resources" directory and add comprehensive resources examples.',
+                initial: true,
+            },
+        ], {
+            onCancel() {
+                logger.error("Addon selection is required.");
+                process.exit(1);
+            },
+        });
+        addonSlidev = addonAnswers.addonSlidev ?? true;
+        addonResources = addonAnswers.addonResources ?? true;
+    }
+    return {
+        directoryName: siteName,
+        projectName: repositoryName,
+        organizationName,
+        repositoryName,
+        title,
+        tagline,
+        addonSlidev,
+        addonResources,
+        gitRepositoryUrl: `https://github.com/${organizationName}/${repositoryName}`,
+        githubPagesUrl: `https://${organizationName}.github.io`,
+        baseUrl: "/",
+    };
+}
+async function copyBaseTemplate(dest) {
+    const baseTemplatePath = path.join(templatesDir, "page-course");
+    await fs.copy(baseTemplatePath, dest);
+    logger.success("Base template copied");
+}
+async function installAddon(dest, addonName) {
+    const addonPath = path.join(templatesDir, addonName);
+    if (addonName === "addon-slidev") {
+        // Copy slidev directory
+        const slidevSrc = path.join(addonPath, "slidev");
+        const slidevDest = path.join(dest, "slidev");
+        await fs.copy(slidevSrc, slidevDest);
+        // Overwrite package.json with the one that includes Slidev dependencies
+        const pkgSrc = path.join(addonPath, "package.json");
+        const pkgDest = path.join(dest, "package.json");
+        await fs.copy(pkgSrc, pkgDest, { overwrite: true });
+        logger.success("Slidev addon installed");
+    }
+    else if (addonName === "addon-resources") {
+        // Copy resources directory
+        const resourcesSrc = path.join(addonPath, "resources");
+        const resourcesDest = path.join(dest, "resources");
+        await fs.copy(resourcesSrc, resourcesDest);
+        logger.success("Resources addon installed");
+    }
+}
+function removeConditionalSections(content, removeMarkers) {
+    let result = content;
+    for (const marker of removeMarkers) {
+        const startMarker = `// CONDITIONAL: ${marker} (START)`;
+        const endMarker = `// CONDITIONAL: ${marker} (END)`;
+        // Remove everything between start and end markers, including the markers
+        const regex = new RegExp(`[ \\t]*${startMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${endMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`, "g");
+        result = result.replace(regex, "");
+    }
+    return result;
+}
+function removeConditionalMarkers(content, keepMarkers) {
+    let result = content;
+    for (const marker of keepMarkers) {
+        const startMarker = `// CONDITIONAL: ${marker} (START)`;
+        const endMarker = `// CONDITIONAL: ${marker} (END)`;
+        // Remove just the markers, keeping the content between them
+        const startRegex = new RegExp(`[ \\t]*${startMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`, "g");
+        const endRegex = new RegExp(`[ \\t]*${endMarker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`, "g");
+        result = result.replace(startRegex, "");
+        result = result.replace(endRegex, "");
+    }
+    return result;
+}
+async function processConditionalMarkers(dest, config) {
+    const markersToRemove = [];
+    const markersToKeep = [];
+    if (!config.addonSlidev) {
+        markersToRemove.push("addon-slidev");
+    }
+    else {
+        markersToKeep.push("addon-slidev");
+    }
+    if (!config.addonResources) {
+        markersToRemove.push("addon-resources");
+    }
+    else {
+        markersToKeep.push("addon-resources");
+    }
+    // Process docusaurus.config.ts
+    const configPath = path.join(dest, "docusaurus.config.ts");
+    let configContent = await fs.readFile(configPath, "utf-8");
+    // First remove sections for disabled addons
+    configContent = removeConditionalSections(configContent, markersToRemove);
+    // Then remove just the markers for enabled addons
+    configContent = removeConditionalMarkers(configContent, markersToKeep);
+    await fs.writeFile(configPath, configContent);
+    // Process index.mdx
+    const indexMdxPath = path.join(dest, "src", "pages", "index.mdx");
+    if (await fs.pathExists(indexMdxPath)) {
+        let indexContent = await fs.readFile(indexMdxPath, "utf-8");
+        // First remove sections for disabled addons
+        indexContent = removeConditionalSections(indexContent, markersToRemove);
+        // Then remove just the markers for enabled addons
+        indexContent = removeConditionalMarkers(indexContent, markersToKeep);
+        await fs.writeFile(indexMdxPath, indexContent);
+    }
+    logger.success("Configuration processed");
+}
+async function processTemplateVariables(dest, config) {
+    // Process docusaurus.config.ts
+    const configPath = path.join(dest, "docusaurus.config.ts");
+    if (await fs.pathExists(configPath)) {
+        let content = await fs.readFile(configPath, "utf-8");
+        // Replace template placeholders
+        content = content
+            .replace(/<%= organizationName %>/g, config.organizationName)
+            .replace(/<%= projectName %>/g, config.projectName)
+            .replace(/<%= gitRepositoryUrl %>/g, config.gitRepositoryUrl)
+            .replace(/<%= title %>/g, config.title)
+            .replace(/<%= tagline %>/g, config.tagline);
+        await fs.writeFile(configPath, content);
+    }
+    // Process package.json
+    const pkgPath = path.join(dest, "package.json");
+    if (await fs.pathExists(pkgPath)) {
+        let content = await fs.readFile(pkgPath, "utf-8");
+        content = content.replace(/<%= projectName %>/g, config.projectName);
+        await fs.writeFile(pkgPath, content);
+    }
+    // Process README.md with conditional sections
+    const readmePath = path.join(dest, "README.md");
+    if (await fs.pathExists(readmePath)) {
+        let content = await fs.readFile(readmePath, "utf-8");
+        // Replace variables
+        content = content
+            .replace(/<%= title %>/g, config.title)
+            .replace(/<%= tagline %>/g, config.tagline)
+            .replace(/<%= directoryName %>/g, config.directoryName)
+            .replace(/<%= organizationName %>/g, config.organizationName)
+            .replace(/<%= repositoryName %>/g, config.repositoryName)
+            .replace(/<%= gitRepositoryUrl %>/g, config.gitRepositoryUrl);
+        // Process conditional sections for addons
+        content = processReadmeConditionals(content, config);
+        await fs.writeFile(readmePath, content);
+    }
+}
+function processReadmeConditionals(content, config) {
+    let result = content;
+    // Process Slidev conditional sections
+    if (!config.addonSlidev) {
+        // Remove sections between <% if (addonSlidev) { %> and <% } %>
+        result = result.replace(/<% if \(addonSlidev\) \{ %>[\s\S]*?<% } %>/g, "");
+    }
+    else {
+        // Remove the conditional markers but keep the content
+        result = result.replace(/<% if \(addonSlidev\) \{ %>\n?/g, "");
+        result = result.replace(/<% } %>\n?/g, "");
+    }
+    // Process Resources conditional sections
+    if (!config.addonResources) {
+        result = result.replace(/<% if \(addonResources\) \{ %>[\s\S]*?<% } %>/g, "");
+    }
+    else {
+        result = result.replace(/<% if \(addonResources\) \{ %>\n?/g, "");
+        result = result.replace(/<% } %>\n?/g, "");
+    }
+    return result;
+}
+async function updatePkg(pkgPath, obj) {
+    const pkg = (await fs.readJSON(pkgPath));
+    const newPkg = Object.assign(pkg, obj);
+    await fs.outputFile(pkgPath, `${JSON.stringify(newPkg, null, 2)}\n`);
+}
+function toKebabCase(str) {
+    return str
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/[\s_]+/g, "-")
+        .toLowerCase();
+}
+export default async function init(rootDir, reqName, cliOptions = {}) {
+    const siteName = await getSiteName(reqName, rootDir);
+    const dest = path.resolve(rootDir, siteName);
+    const config = await getProjectConfig(siteName, cliOptions);
+    logger.info("Creating a new SP-Days site...");
+    // Copy base template
+    await copyBaseTemplate(dest);
+    // Install addons if requested
+    if (config.addonSlidev) {
+        await installAddon(dest, "addon-slidev");
+    }
+    if (config.addonResources) {
+        await installAddon(dest, "addon-resources");
+    }
+    // Process conditional markers in docusaurus.config.ts
+    await processConditionalMarkers(dest, config);
+    // Process template variables
+    await processTemplateVariables(dest, config);
+    // Update package.json info.
+    try {
+        await updatePkg(path.join(dest, "package.json"), {
+            name: toKebabCase(config.projectName),
+            version: "0.0.0",
+            private: true,
+        });
+    }
+    catch (err) {
+        logger.error("Failed to update package.json.");
+        throw err;
+    }
+    // We need to rename the gitignore file to .gitignore
+    if (!(await fs.pathExists(path.join(dest, ".gitignore"))) &&
+        (await fs.pathExists(path.join(dest, "gitignore")))) {
+        await fs.move(path.join(dest, "gitignore"), path.join(dest, ".gitignore"));
+    }
+    if (await fs.pathExists(path.join(dest, "gitignore"))) {
+        await fs.remove(path.join(dest, "gitignore"));
+    }
+    // Display the most elegant way to cd.
+    const cdpath = path.relative(".", dest);
+    const pkgManager = await getPackageManager(dest, cliOptions);
+    if (!cliOptions.skipInstall) {
+        process.chdir(dest);
+        logger.info `Installing dependencies with name=${pkgManager}...`;
+        if ((await execa.command(pkgManager === "yarn"
+            ? "yarn"
+            : pkgManager === "bun"
+                ? "bun install"
+                : `${pkgManager} install --color always`, {
+            env: {
+                ...process.env,
+                // Force coloring the output
+                ...(supportsColor.stdout ? { FORCE_COLOR: "1" } : {}),
+            },
+        })).exitCode !== 0) {
+            logger.error("Dependency installation failed.");
+            logger.info `The site directory has already been created, and you can retry by typing:
+
+  code=${`cd ${cdpath}`}
+  code=${`${pkgManager} install`}`;
+            process.exit(0);
+        }
+        logger.success("Dependencies installed");
+    }
+    const useNpm = pkgManager === "npm";
+    const useBun = pkgManager === "bun";
+    const useRunCommand = useNpm || useBun;
+    logger.success `Created name=${config.projectName} at path=${cdpath}.`;
+    logger.info `Inside that directory, you can run several commands:
+
+  code=${`${pkgManager} start`}
+    Starts the development server.
+
+  code=${`${pkgManager} ${useRunCommand ? "run " : ""}build`}
+    Bundles your website into static files for production.
+
+  code=${`${pkgManager} ${useRunCommand ? "run " : ""}serve`}
+    Serves the built website locally.${config.addonSlidev
+        ? `
+
+  code=${`${pkgManager} ${useRunCommand ? "run " : ""}slidev`}
+    Launches Slidev presentation server.`
+        : ""}
+
+We suggest that you begin by typing:
+
+  code=${`cd ${cdpath}`}
+  code=${`${pkgManager} start`}
+
+Happy days! 📚
+`;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@sp-days-framework/create-sp-days",
+  "version": "1.0.0",
+  "description": "Scaffolding tool for creating SP-Days course websites built on Docusaurus and Slidev.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/helse-sorost/sp-days-framework",
+    "directory": "create-sp-days"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "watch": "tsc --build --watch"
+  },
+  "bin": "bin/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/logger": "3.9.2",
+    "@docusaurus/types": "3.9.2",
+    "commander": "^5.1.0",
+    "execa": "5.1.1",
+    "fs-extra": "^11.1.1",
+    "prompts": "^2.4.2",
+    "semver": "^7.5.4",
+    "supports-color": "^9.4.0",
+    "tslib": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/prompts": "^2.4.9",
+    "@types/semver": "^7.5.6",
+    "@types/supports-color": "^8.1.1",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=20.0"
+  }
+}

package/templates/addon-resources/resources/frontpage-collection/components/Columns.mdx

@@ -0,0 +1,191 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import {
+  Columns,
+  Left,
+  Right,
+  Block,
+} from "@sp-days-framework/docusaurus-frontpage-collection";
+
+# Columns Section
+
+Create responsive two-column layouts with customizable ratios.
+
+<div className="preview">
+  <div className="container" style={{ width: '-webkit-fill-available'}}>
+    <Columns leftRatio="60">
+      <Left>
+        ### Main Content
+        
+        This is a live example of the Columns component. The left column takes up 60% of the width, while the right column takes up 40%.
+        
+        The columns will automatically stack on smaller screens for better mobile experience.
+      </Left>
+      <Right>
+        <Block>
+          ### Quick Stats
+          
+          - **Responsive**: Stacks on mobile
+          - **Flexible**: Custom ratios
+          - **Equal height**: Automatic
+        </Block>
+      </Right>
+    </Columns>
+  </div>
+</div>
+
+## Features
+
+- Flexible column ratios
+- Equal height option
+- Automatic text wrapping
+
+## Import
+
+<Tabs>
+  <TabItem value="individual" label="Individual import" default>
+    ```mdx
+    import {
+      Columns,
+      Left,
+      Right,
+    } from "@sp-days-framework/docusaurus-frontpage-collection";
+    ```
+  </TabItem>
+  <TabItem value="default" label="Default import">
+    ```mdx
+    import Columns, { Left, Right } from "@sp-days-framework/docusaurus-frontpage-collection/lib/components/Columns";
+    ```
+  </TabItem>
+</Tabs>
+
+## Basic Usage
+
+```mdx
+<Columns>
+  <Left>
+    Left column content
+  </Left>
+  <Right>
+    Right column content
+  </Right>
+</Columns>
+```
+
+## Props
+
+### Columns
+
+| Prop          | Type        | Default   | Description                              |
+| ------------- | ----------- | --------- | ---------------------------------------- |
+| `leftRatio`   | `string`    | `'50'`    | Width percentage for left column         |
+| `equalHeight` | `boolean`   | `true`    | Whether columns should have equal height |
+| `minWidth`    | `string`    | `'700px'` | Minimum width before stacking            |
+| `noStretch`   | `boolean`   | `false`   | Prevent columns from stretching          |
+| `children`    | `ReactNode` | required  | Left and Right components                |
+
+### Left / Right
+
+| Prop       | Type        | Description                   |
+| ---------- | ----------- | ----------------------------- |
+| `children` | `ReactNode` | Column content (supports MDX) |
+
+## Examples
+
+### 50/50 Split
+
+```mdx
+<Columns>
+  <Left>
+    ## Left Side
+    
+    Content for the left column
+  </Left>
+  <Right>
+    ## Right Side
+    
+    Content for the right column
+  </Right>
+</Columns>
+```
+
+### 60/40 Split
+
+```mdx
+<Columns leftRatio="60">
+  <Left>
+    ## Main Content (60%)
+    
+    This column takes up 60% of the width
+  </Left>
+  <Right>
+    ## Sidebar (40%)
+    
+    This column takes up 40% of the width
+  </Right>
+</Columns>
+```
+
+### 70/30 Split
+
+```mdx
+<Columns leftRatio="70">
+  <Left>
+    ## Primary Content
+    
+    Larger column for main content
+  </Left>
+  <Right>
+    ### Quick Stats
+    
+    - Duration: 4 weeks
+    - Effort: 10 hrs/week
+  </Right>
+</Columns>
+```
+
+### With Block Component
+
+```mdx
+import {
+  Columns,
+  Left,
+  Right,
+  Block,
+} from "@sp-days-framework/docusaurus-frontpage-collection";
+
+<Columns leftRatio="65">
+  <Left>
+    ## Course Overview
+    
+    Detailed description of the course...
+  </Left>
+  <Right>
+    <Block>
+      ### Info
+      
+      - **Level**: Intermediate
+      - **Duration**: 6 weeks
+      - **Certificate**: Yes
+    </Block>
+  </Right>
+</Columns>
+```
+
+## Responsive Behavior
+
+The columns automatically stack vertically when the container is too narrow:
+
+- **> 900px**: Full two-column layout
+- **750px - 900px**: Reduced gap between columns
+- **600px - 750px**: Further adjusted spacing
+- **< 600px**: Stacks vertically
+
+## Content Wrapping
+
+Text and content automatically wrap within columns:
+
+- Long words break appropriately
+- Tables become scrollable
+- Images scale to fit
+- Code blocks wrap or scroll