@sp-days-framework/create-sp-days 1.0.4 → 1.1.0-beta1

package/lib/index.js

@@ -155,16 +155,20 @@ async function getProjectConfig(siteName, cliOptions) {
     // Get addon selections
     let addonSlidev;
     let addonResources;
+    let includePackageDocs;
     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;
+        includePackageDocs = cliOptions.includePackageDocs ?? false;
     }
     else if (cliOptions.addonSlidev !== undefined ||
-        cliOptions.addonResources !== undefined) {
+        cliOptions.addonResources !== undefined ||
+        cliOptions.includePackageDocs !== undefined) {
         // Addon flags provided without config flags
         addonSlidev = cliOptions.addonSlidev ?? false;
         addonResources = cliOptions.addonResources ?? false;
+        includePackageDocs = cliOptions.includePackageDocs ?? false;
     }
     else {
         // Interactive mode - prompt with default yes
@@ -181,6 +185,12 @@ async function getProjectConfig(siteName, cliOptions) {
                 message: 'Do you wish to add a Resources page?\n  This will add a "./resources" directory and add comprehensive resources examples.',
                 initial: true,
             },
+            {
+                type: "confirm",
+                name: "includePackageDocs",
+                message: "Do you wish to include package documentation?\n  Useful for package development and easier access to docs, but adds unnecessary dependencies for production builds.\n  You can remove this later (see README for instructions).",
+                initial: false,
+            },
         ], {
             onCancel() {
                 logger.error("Addon selection is required.");
@@ -189,6 +199,7 @@ async function getProjectConfig(siteName, cliOptions) {
         });
         addonSlidev = addonAnswers.addonSlidev ?? true;
         addonResources = addonAnswers.addonResources ?? true;
+        includePackageDocs = addonAnswers.includePackageDocs ?? false;
     }
     return {
         directoryName: siteName,
@@ -199,6 +210,7 @@ async function getProjectConfig(siteName, cliOptions) {
         tagline,
         addonSlidev,
         addonResources,
+        includePackageDocs,
         gitRepositoryUrl: `https://github.com/${organizationName}/${repositoryName}`,
         githubPagesUrl: `https://${organizationName}.github.io`,
         baseUrl: "/",
@@ -216,10 +228,6 @@ async function installAddon(dest, addonName) {
         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") {
@@ -257,7 +265,9 @@ function removeConditionalMarkers(content, keepMarkers) {
 async function processConditionalMarkers(dest, config) {
     const markersToRemove = [];
     const markersToKeep = [];
-    if (!config.addonSlidev) {
+    // Slidev addon should be kept if either addonSlidev OR includePackageDocs is enabled
+    const shouldKeepSlidev = config.addonSlidev || config.includePackageDocs;
+    if (!shouldKeepSlidev) {
         markersToRemove.push("addon-slidev");
     }
     else {
@@ -269,6 +279,12 @@ async function processConditionalMarkers(dest, config) {
     else {
         markersToKeep.push("addon-resources");
     }
+    if (!config.includePackageDocs) {
+        markersToRemove.push("package-docs");
+    }
+    else {
+        markersToKeep.push("package-docs");
+    }
     // Process docusaurus.config.ts
     const configPath = path.join(dest, "docusaurus.config.ts");
     let configContent = await fs.readFile(configPath, "utf-8");
@@ -287,6 +303,16 @@ async function processConditionalMarkers(dest, config) {
         indexContent = removeConditionalMarkers(indexContent, markersToKeep);
         await fs.writeFile(indexMdxPath, indexContent);
     }
+    // Process package.json
+    const pkgPath = path.join(dest, "package.json");
+    if (await fs.pathExists(pkgPath)) {
+        let pkgContent = await fs.readFile(pkgPath, "utf-8");
+        // First remove sections for disabled addons
+        pkgContent = removeConditionalSections(pkgContent, markersToRemove);
+        // Then remove just the markers for enabled addons
+        pkgContent = removeConditionalMarkers(pkgContent, markersToKeep);
+        await fs.writeFile(pkgPath, pkgContent);
+    }
     logger.success("Configuration processed");
 }
 async function processTemplateVariables(dest, config) {
@@ -367,8 +393,11 @@ export default async function init(rootDir, reqName, cliOptions = {}) {
     logger.info("Creating a new SP-Days site...");
     // Copy base template
     await copyBaseTemplate(dest);
+    // If package docs are enabled, ensure Slidev addon is also installed
+    // (package docs include Slidev theme documentation, so we need the addon)
+    const shouldInstallSlidev = config.addonSlidev || config.includePackageDocs;
     // Install addons if requested
-    if (config.addonSlidev) {
+    if (shouldInstallSlidev) {
         await installAddon(dest, "addon-slidev");
     }
     if (config.addonResources) {

package/package.json

@@ -1,22 +1,46 @@
 {
   "name": "@sp-days-framework/create-sp-days",
-  "version": "1.0.4",
+  "version": "1.1.0-beta1",
   "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",
+    "url": "git+https://github.com/helse-sorost/sp-days-framework.git",
     "directory": "create-sp-days"
   },
-  "scripts": {
-    "build": "tsc --build",
-    "watch": "tsc --build --watch"
+  "author": "SP-Days Framework",
+  "license": "MIT",
+  "keywords": [
+    "docusaurus",
+    "scaffolding",
+    "cli",
+    "sp-days",
+    "course",
+    "training"
+  ],
+  "bin": {
+    "create-sp-days": "bin/index.js"
+  },
+  "files": [
+    "bin/**/*",
+    "lib/**/*",
+    "templates/**/*",
+    "tsconfig.*.json",
+    "docs/**/*",
+    "publish-package-docs.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./publish-package-docs": "./publish-package-docs.js"
   },
-  "bin": "bin/index.js",
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT",
+  "scripts": {
+    "build": "tsc --build",
+    "watch": "tsc --build --watch"
+  },
   "dependencies": {
     "@docusaurus/logger": "3.9.2",
     "@docusaurus/types": "3.9.2",

package/publish-package-docs.js

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+module.exports = {
+  id: "create-sp-days-docs",
+  path: require("path").join(__dirname, "docs"),
+  routeBasePath: "package-docs/create-sp-days",
+};

package/templates/addon-resources/resources/api-reference.mdx

@@ -0,0 +1,132 @@
+---
+sidebar_label: "API Reference"
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 1
+---
+
+{/*
+
+API Reference pages document REST, GraphQL, or other API endpoints with details about 
+parameters, request/response formats, and authentication. Keep examples realistic and 
+include error cases. Use tables for parameter documentation to maintain consistency.
+
+*/}
+
+
+# API Reference Template
+
+Comprehensive documentation for all available API endpoints, including request parameters, response formats, and authentication requirements.
+
+## Authentication
+
+All API requests require authentication using an API key passed in the `Authorization` header.
+
+```http
+Authorization: Bearer YOUR_API_KEY
+```
+
+## Base URL
+
+```
+https://api.example.com/v1
+```
+
+## Endpoints
+
+### GET /resource
+
+Retrieve a list of resources.
+
+**Parameters:**
+
+| Name    | Type     | Required | Description                           |
+|---------|----------|----------|---------------------------------------|
+| `limit` | integer  | No       | Maximum number of results (default: 10) |
+| `page`  | integer  | No       | Page number for pagination (default: 1) |
+| `sort`  | string   | No       | Sort field and order (e.g., `name:asc`) |
+
+**Example Request:**
+
+```bash
+curl -X GET "https://api.example.com/v1/resource?limit=5&page=1" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+**Example Response:**
+
+```json
+{
+  "data": [
+    {
+      "id": "123",
+      "name": "Example Resource",
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "meta": {
+    "total": 42,
+    "page": 1,
+    "limit": 5
+  }
+}
+```
+
+### POST /resource
+
+Create a new resource.
+
+**Request Body:**
+
+| Field        | Type   | Required | Description                    |
+|--------------|--------|----------|--------------------------------|
+| `name`       | string | Yes      | Name of the resource           |
+| `description`| string | No       | Optional description           |
+
+**Example Request:**
+
+```bash
+curl -X POST "https://api.example.com/v1/resource" \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "New Resource",
+    "description": "A sample resource"
+  }'
+```
+
+**Example Response:**
+
+```json
+{
+  "id": "124",
+  "name": "New Resource",
+  "description": "A sample resource",
+  "created_at": "2024-01-15T10:35:00Z"
+}
+```
+
+## Error Responses
+
+| Status Code | Description                       |
+|-------------|-----------------------------------|
+| 400         | Bad Request - Invalid parameters  |
+| 401         | Unauthorized - Invalid API key    |
+| 404         | Not Found - Resource doesn't exist|
+| 429         | Too Many Requests - Rate limited  |
+| 500         | Internal Server Error             |
+
+**Example Error Response:**
+
+```json
+{
+  "error": {
+    "code": "invalid_parameter",
+    "message": "The 'limit' parameter must be between 1 and 100"
+  }
+}
+```
+
+:::tip Rate Limits
+API requests are limited to 100 requests per minute per API key. Check the `X-RateLimit-Remaining` header in responses.
+:::

package/templates/addon-resources/resources/best-practice.mdx

@@ -0,0 +1,407 @@
+---
+sidebar_label: Best Practices
+sidebar_position: 1
+---
+
+# Docusaurus Best Practices & Guidelines
+
+Recommended practices for writing high-quality Docusaurus documentation using MDX format.
+
+## File Format
+
+Always use `.mdx` extension for Docusaurus documentation files, even if not currently using JSX components.
+
+**Benefits:**
+- Enables use of Docusaurus MDX components (Tabs, Admonitions, etc.)
+- Provides consistency across the documentation
+- Makes files less portable but more powerful within Docusaurus ecosystem
+
+```
+✅ quick-start.mdx
+❌ quick-start.md
+```
+
+## Frontmatter
+
+Frontmatter fields are optional but useful for customization.
+
+| Field | Purpose | Example |
+|-------|---------|---------|
+| `sidebar_label` | Shorter sidebar title or add icons | `sidebar_label: 🚀 Quick Start` |
+| `sidebar_position` | Override alphabetical ordering | `sidebar_position: 1` |
+| `title` | Override H1 as page title | `title: Getting Started Guide` |
+
+Use `sidebar_label` when your H1 heading is too long for the sidebar, or to add emoji/icons for visual distinction.
+
+**Alternative to `sidebar_position`:** Prefix filenames with numbers like `01-introduction.mdx`, `02-installation.mdx`, `03-configuration.mdx`.
+
+## Component Imports
+
+Always place imports immediately after frontmatter:
+
+````mdx
+---
+sidebar_label: Examples
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Examples and Usage
+````
+
+## Heading Structure
+
+Never skip heading levels – maintain logical document structure for accessibility.
+
+```mdx
+✅ Good
+# Main Title (H1)
+## Section (H2)
+### Subsection (H3)
+#### Detail (H4)
+
+❌ Bad
+# Main Title (H1)
+### Subsection (H3)  ← Skipped H2
+```
+
+Don't create sections with only one sub-heading – it creates awkward TOC entries.
+
+```mdx
+❌ Bad
+## Configuration
+### Database Setup  ← Only one H3 under H2
+
+✅ Better - Remove sub-header
+## Database Setup
+
+✅ Better - Add more sub-headers
+## Configuration
+### Database Setup
+### Cache Setup
+### Logging Setup
+```
+
+Adjust TOC depth using frontmatter if using many H4 headings:
+
+```mdx
+---
+tableOfContents:
+  maxHeadingLevel: 3
+---
+
+# My Page
+```
+
+## Code Blocks
+
+Always specify the language for proper syntax highlighting:
+
+````mdx
+✅ Good
+```bash
+npm install
+```
+
+❌ Bad
+```
+npm install
+```
+````
+
+Use `title` attribute for known filenames or configuration files:
+
+````mdx
+```json title="package.json"
+{
+  "name": "my-app",
+  "version": "1.0.0"
+}
+```
+````
+
+Highlight specific lines when showing modifications:
+
+````mdx
+```typescript title="app.ts" {3-5}
+function greet(name: string) {
+  // highlight-next-line
+  console.log(`Hello, ${name}!`);
+  return `Welcome, ${name}`;
+}
+```
+````
+
+Use backslash `\` for lengthy commands to improve readability:
+
+```bash
+docker run -d \
+  --name my-container \
+  --publish 8080:80 \
+  --volume $(pwd):/app \
+  nginx:latest
+```
+
+For multiple commands, use one of these approaches:
+
+````mdx
+Option 1: Separate blocks
+```bash
+npm install
+```
+
+```bash
+npm run dev
+```
+
+Option 2: Chain with &&
+```bash
+npm install && npm run dev
+```
+
+Option 3: Use comments
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+````
+
+## Inline Code vs Code Blocks
+
+Use inline code for short, single-line references:
+
+- File paths: `src/components/Header.tsx`
+- Variables: `API_KEY`
+- Functions: `getUserById()`
+- Small values: `true`, `null`, `"production"`
+- Commands when mentioned in text: "Run `npm install` to get started"
+
+Use code blocks for:
+
+- Commands in step-by-step instructions or when you expect readers to copy
+- Complete commands with options
+- Configuration files
+- Function/class implementations
+- Multi-step procedures
+
+## MDX Components
+
+Don't use markdown headers inside Tabs components – they appear in the TOC. Use bold text or `<h3>` tags instead.
+
+````mdx
+❌ Bad
+<Tabs>
+  <TabItem value="npm">
+    ### Using npm  ← Appears in TOC
+    ```bash
+    npm install
+    ```
+  </TabItem>
+</Tabs>
+
+✅ Good - Use bold text
+<Tabs>
+  <TabItem value="npm">
+
+    **Using npm**
+
+    ```bash
+    npm install
+    ```
+
+  </TabItem>
+</Tabs>
+
+✅ Good - Use <h3> tag
+<Tabs>
+  <TabItem value="npm">
+
+    <h3>Using npm</h3>
+
+    ```bash
+    npm install
+    ```
+
+  </TabItem>
+</Tabs>
+````
+
+Maintain proper indentation for nested HTML/JSX:
+
+````mdx
+<details>
+  <summary>Click to expand</summary>
+
+  <div>
+    <p>Nested content should be indented</p>
+    <ul>
+      <li>Item 1</li>
+      <li>Item 2</li>
+    </ul>
+  </div>
+
+</details>
+````
+
+## Admonitions
+
+Admonitions steal focus (intentionally) – use only for important information. Limit to 1-2 per page section.
+
+````mdx
+:::note
+General information or context
+:::
+
+:::tip
+Helpful shortcuts or best practices
+:::
+
+:::warning
+Potential pitfalls or deprecated features
+:::
+
+:::danger
+Destructive actions or critical warnings
+:::
+
+:::info
+Additional context or related information
+:::
+````
+
+**When to use:**
+
+- `:::note` – Additional context that's helpful but not critical
+- `:::tip` – Efficiency shortcuts or recommended approaches
+- `:::warning` – Potential issues, deprecated features, or gotchas
+- `:::danger` – Data loss risks, breaking changes, security concerns
+- `:::info` – Related resources or background information
+
+## Tables
+
+Use markdown tables for structured data like command options, configuration parameters, comparison matrices, or property documentation.
+
+````mdx
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | number | `3000` | Server port |
+| `host` | string | `localhost` | Server host |
+````
+
+Keep column count reasonable and use concise headers for readability.
+
+## Collapsible Sections
+
+Hide advanced or supplementary information behind collapsible sections using `<details>`:
+
+````mdx
+<details>
+  <summary>Advanced configuration options</summary>
+
+  Content here is hidden by default and revealed on click.
+
+  ```json
+  {
+    "advanced": true
+  }
+  ```
+
+</details>
+````
+
+**When to use:**
+
+- Advanced configuration options
+- Detailed explanations for specific edge cases
+- Lengthy reference information
+- Optional troubleshooting steps
+
+## Directory Structure
+
+Consider adding an `index.mdx` landing page in directories when the category needs an overview, navigation to sub-pages, or general context.
+
+```
+guides/
+├── index.mdx          ← Landing page for guides section
+├── installation.mdx
+├── configuration.mdx
+└── deployment.mdx
+```
+
+## Links
+
+Markdown links are useful but require careful consideration.
+
+**Pros:**
+- Great for connecting related documentation
+- Improve content discoverability
+- Enable quick navigation
+
+**Cons:**
+- Break when files are moved or renamed
+- Create maintenance burden in large projects
+- Can cause build errors if targets are deleted
+
+**Guideline:**
+
+- Use links in `index.mdx` landing pages for navigation
+- Avoid excessive cross-linking in regular content pages
+- Prefer sidebar navigation over inline links when possible
+- Keep external links (to official docs, resources) – they're valuable
+
+````mdx
+✅ Good - Landing page with curated links
+# Getting Started
+
+- [Installation Guide](./installation.mdx)
+- [Configuration](./configuration.mdx)
+
+✅ Good - External resource
+See the [official Docker documentation](https://docs.docker.com)
+
+⚠️ Use sparingly - Cross-references between regular pages
+For database setup, see [Configuration Guide](../config/database.mdx)
+````
+
+## Images & Assets
+
+Store page-specific images in `.assets/` directory alongside the MDX file:
+
+```
+guides/
+├── installation.mdx
+└── .assets/
+    ├── install-step1.png
+    └── install-step2.png
+```
+
+Store shared resources in `/static/img/` for logos, icons, and reused graphics:
+
+```
+static/
+└── img/
+    ├── logo.svg
+    ├── docker-icon.png
+    └── common/
+        └── warning-icon.svg
+```
+
+Always include descriptive alt text for images:
+
+````mdx
+✅ Good
+![Docker container architecture diagram showing layers](./assets/docker-architecture.png)
+
+❌ Bad
+![](./assets/image.png)
+````
+
+**Performance tips:**
+
+- Prefer SVG for logos and icons (smaller, scalable)
+- Optimize PNG/JPG images before adding to repository
+- Use appropriate image dimensions (don't scale down huge images with HTML)