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

package/templates/addon-resources/resources/quick-start.mdx

@@ -0,0 +1,193 @@
+---
+sidebar_label: "Quick Start"
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 1
+---
+
+{/*
+
+Quick Start pages help users achieve their first success as quickly as possible. Focus on 
+the minimal steps needed to get started, avoiding deep explanations. Use numbered steps and 
+verification checkpoints. Link to comprehensive guides for users who want to learn more.
+
+*/}
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Quick Start Template
+
+Get up and running in just a few minutes with this step-by-step guide.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- Basic familiarity with the command line
+- An active internet connection
+- Administrator/sudo access (for installation)
+
+## Installation
+
+Choose your platform and follow the installation command:
+
+<Tabs groupId="operating-systems">
+<TabItem value="linux" label="Linux">
+
+```bash
+curl -fsSL https://example.com/install.sh | bash
+```
+
+</TabItem>
+<TabItem value="macos" label="macOS">
+
+```bash
+brew install example-tool
+```
+
+</TabItem>
+<TabItem value="windows" label="Windows">
+
+```powershell
+winget install Example.Tool
+```
+
+</TabItem>
+</Tabs>
+
+**Verify installation:**
+
+```bash
+example-tool --version
+```
+
+Expected output: `example-tool version 1.2.3`
+
+## Create Your First Project
+
+### Step 1: Initialize
+
+Create a new directory and initialize the project:
+
+```bash
+mkdir my-first-project
+cd my-first-project
+example-tool init
+```
+
+You'll see a success message:
+
+```
+✓ Project initialized successfully
+✓ Configuration file created: config.yml
+✓ Ready to get started!
+```
+
+### Step 2: Configure
+
+Set up your basic configuration:
+
+```bash
+example-tool config set project.name "My First Project"
+example-tool config set user.name "Your Name"
+```
+
+**Verify configuration:**
+
+```bash
+example-tool config show
+```
+
+### Step 3: Create a Resource
+
+Create your first resource:
+
+```bash
+example-tool create item hello-world --description "My first resource"
+```
+
+Output:
+
+```
+✓ Created resource: hello-world (id: abc123)
+```
+
+### Step 4: View Your Resource
+
+List all resources to see what you've created:
+
+```bash
+example-tool list
+```
+
+## Working with Configuration Files
+
+Instead of using CLI commands, you can define resources in a configuration file:
+
+```yaml title="resources.yml"
+resources:
+  - name: resource-one
+    type: item
+    description: First resource
+    tags:
+      - example
+      - demo
+  
+  - name: resource-two
+    type: item
+    description: Second resource
+    tags:
+      - example
+```
+
+**Apply the configuration:**
+
+```bash
+example-tool apply --file resources.yml
+```
+
+## Next Steps
+
+Congratulations! You've completed the quick start guide. Here's what to explore next:
+
+1. **Learn More Commands:** Check out the [CLI Reference](#) for all available commands
+2. **Advanced Configuration:** Read the [Configuration Guide](#) for customization options
+3. **Troubleshooting:** Visit the [Troubleshooting](#) page if you encounter issues
+4. **API Usage:** Explore the [API Reference](#) for programmatic access
+
+## Quick Reference
+
+### Essential Commands
+
+| Command                  | Description                    |
+|--------------------------|--------------------------------|
+| `example-tool init`      | Initialize a new project       |
+| `example-tool create`    | Create a new resource          |
+| `example-tool list`      | List all resources             |
+| `example-tool info <id>` | Show resource details          |
+| `example-tool update <id>` | Update a resource            |
+| `example-tool delete <id>` | Delete a resource            |
+| `example-tool help`      | Show help information          |
+
+### Useful Options
+
+| Option            | Description                      |
+|-------------------|----------------------------------|
+| `--help, -h`      | Display help for any command     |
+| `--verbose, -v`   | Show detailed output             |
+| `--output, -o`    | Format output (json, yaml, table)|
+| `--force, -f`     | Skip confirmation prompts        |
+
+## Getting Help
+
+If you need assistance:
+
+- Run `example-tool help` for command documentation
+- Check the [FAQ](#) for common questions
+- Visit our [community forum](https://forum.example.com)
+- Report issues on [GitHub](https://github.com/example/tool/issues)
+
+:::tip Pro Tip
+Use `example-tool --help` or `example-tool <command> --help` to see detailed information about any command and its options.
+:::

package/templates/addon-resources/resources/troubleshooting.mdx

@@ -0,0 +1,263 @@
+---
+sidebar_label: "Troubleshooting"
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 1
+---
+
+{/*
+
+Troubleshooting pages help users diagnose and resolve common issues. Organize by error type 
+or symptom. Provide clear problem descriptions, root causes, and step-by-step solutions. 
+Include command examples and expected outputs for verification.
+
+*/}
+
+# Troubleshooting Template
+
+Solutions to common issues and error messages you may encounter.
+
+## Installation Issues
+
+### Command Not Found After Installation
+
+**Problem:** Running `example-tool` returns "command not found" error.
+
+**Cause:** The installation directory is not in your system's PATH.
+
+**Solution:**
+
+```bash
+# Check if the tool is installed
+which example-tool
+
+# Add to PATH (temporary)
+export PATH="$PATH:/usr/local/bin"
+
+# Add to PATH (permanent - add to ~/.bashrc or ~/.zshrc)
+echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Verify:**
+
+```bash
+example-tool --version
+```
+
+### Permission Denied
+
+**Problem:** Installation fails with "permission denied" error.
+
+**Cause:** Insufficient permissions to write to installation directory.
+
+**Solution:**
+
+```bash
+# On Linux/macOS, use sudo
+sudo example-tool install
+
+# Or install to user directory
+example-tool install --user
+
+# Make binary executable
+chmod +x /usr/local/bin/example-tool
+```
+
+### SSL Certificate Verification Failed
+
+**Problem:** Download fails with SSL certificate errors.
+
+**Cause:** Corporate proxy, outdated certificates, or network security settings.
+
+**Solution:**
+
+```bash
+# Update CA certificates (Ubuntu/Debian)
+sudo apt-get update && sudo apt-get install ca-certificates
+
+# macOS
+brew install ca-certificates
+
+# As last resort (not recommended for production)
+curl -k https://example.com/install.sh | bash
+```
+
+## Configuration Issues
+
+### Configuration File Not Found
+
+**Problem:** Tool reports "configuration file not found" error.
+
+**Cause:** No config file exists in the expected locations.
+
+**Solution:**
+
+```bash
+# Create default configuration
+example-tool init
+
+# Or create manually
+mkdir -p ~/.config/example-tool
+cat > ~/.config/example-tool/config.yml << EOF
+app:
+  name: my-app
+  environment: development
+EOF
+```
+
+**Verify:**
+
+```bash
+example-tool config show
+```
+
+### Invalid Configuration Syntax
+
+**Problem:** Error message: "Invalid YAML syntax" or "Failed to parse configuration".
+
+**Cause:** Syntax errors in the configuration file.
+
+**Solution:**
+
+```bash
+# Validate configuration
+example-tool config validate
+
+# Check for common issues:
+# - Incorrect indentation (use spaces, not tabs)
+# - Missing colons after keys
+# - Unquoted special characters
+
+# View line-by-line
+cat -n ~/.config/example-tool/config.yml
+```
+
+### Environment Variables Not Working
+
+**Problem:** Environment variables are not overriding configuration values.
+
+**Cause:** Incorrect variable names or not exported.
+
+**Solution:**
+
+```bash
+# Check current environment variables
+env | grep EXAMPLE
+
+# Export variables correctly
+export EXAMPLE_API_KEY="your-key"
+export EXAMPLE_ENDPOINT="https://api.example.com"
+
+# Verify they're loaded
+example-tool config show --effective
+```
+
+## Common Error Messages
+
+### Error: "Port already in use"
+
+**Solution:**
+
+```bash
+# Find process using the port
+lsof -ti:8080
+
+# Kill the process
+kill -9 $(lsof -ti:8080)
+
+# Or use a different port
+example-tool start --port 9000
+```
+
+### Error: "Disk quota exceeded"
+
+**Solution:**
+
+```bash
+# Check disk usage
+df -h
+
+# Clean up cache
+example-tool cache clear
+
+# Remove old logs
+rm -rf ~/.config/example-tool/logs/*.log
+```
+
+### Error: "Unable to lock file"
+
+**Solution:**
+
+```bash
+# Find and remove stale lock files
+find ~/.config/example-tool -name "*.lock" -delete
+
+# Or wait for existing operation to complete
+ps aux | grep example-tool
+```
+
+## Debugging
+
+### Enable Verbose Logging
+
+```bash
+# Enable debug output
+example-tool --verbose command
+
+# Or set log level
+export LOG_LEVEL=debug
+example-tool command
+
+# Save logs to file
+example-tool --verbose command 2>&1 | tee debug.log
+```
+
+### Run Diagnostics
+
+```bash
+# Run health check
+example-tool doctor
+
+# Verify system requirements
+example-tool check-system
+
+# Test connectivity
+example-tool test connection
+```
+
+### Inspect Network Traffic
+
+```bash
+# Enable HTTP debugging
+export DEBUG=http
+example-tool command
+
+# Use curl to test API directly
+curl -v -H "Authorization: Bearer YOUR_KEY" \
+  https://api.example.com/v1/resource
+```
+
+## Getting Additional Help
+
+If these solutions don't resolve your issue:
+
+1. **Check logs:** `~/.config/example-tool/logs/`
+2. **Search issues:** [GitHub Issues](https://github.com/example/tool/issues)
+3. **Ask the community:** [Forum](https://forum.example.com)
+4. **Contact support:** support@example.com
+
+When reporting issues, include:
+- Tool version (`example-tool --version`)
+- Operating system and version
+- Complete error message
+- Steps to reproduce
+- Relevant configuration (remove sensitive data)
+
+:::tip Quick Diagnostics
+Run `example-tool doctor` to automatically check for common configuration and environment issues.
+:::
+
+:::warning Before Reinstalling
+Try `example-tool repair` to fix common issues without losing your configuration.
+:::

package/templates/addon-resources/resources/useful-links.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_label: "Useful Links"
+sidebar_custom_props:
+  section: "Templates"
+  section_position: 1
+---
+
+{/*
+
+Useful Links pages curate external resources, official documentation, community forums, and 
+learning materials. Organize by category and provide brief descriptions of what each resource 
+offers. Keep links current and verify they're active.
+
+*/}
+
+# Useful Links Template Template
+
+Curated collection of external resources, documentation, and community links to help you learn and grow.
+
+## Official Resources
+
+### Documentation
+
+- **[Official Documentation](https://example.com/docs)** – Complete reference and guides
+- **[API Documentation](https://api.example.com/docs)** – REST API reference with interactive examples
+- **[Release Notes](https://example.com/releases)** – Latest updates and changelog
+- **[Roadmap](https://example.com/roadmap)** – Planned features and future development
+
+### Downloads
+
+- **[Installation Packages](https://example.com/downloads)** – Official installers for all platforms
+- **[Docker Images](https://hub.docker.com/r/example/tool)** – Official container images
+- **[Source Code](https://github.com/example/tool)** – GitHub repository
+
+### Support
+
+- **[Issue Tracker](https://github.com/example/tool/issues)** – Report bugs and request features
+- **[Security Policy](https://example.com/security)** – How to report security vulnerabilities
+- **[Support Portal](https://support.example.com)** – Enterprise support and SLA information
+
+## Learning Resources
+
+### Tutorials & Guides
+
+- **[Getting Started Tutorial](https://example.com/tutorial)** – Official beginner's guide
+- **[Video Course](https://example.com/learn)** – Comprehensive video training
+- **[Interactive Playground](https://playground.example.com)** – Try it online without installing
+- **[Example Projects](https://github.com/example/examples)** – Sample implementations
+
+### Best Practices
+
+- **[Architecture Guide](https://example.com/architecture)** – Design patterns and best practices
+- **[Security Best Practices](https://example.com/security-guide)** – How to use securely
+- **[Performance Optimization](https://example.com/performance)** – Tips for optimal performance
+- **[Production Deployment](https://example.com/production)** – Production-ready configurations
+
+---
+
+:::note External Links
+These links point to external websites not controlled by this project. We are not responsible for their content or availability.
+:::

package/templates/page-course/README.md

@@ -150,3 +150,65 @@ More content
 See the [Slidev documentation](https://sli.dev/) for the full syntax.
 
 <% } %>
+
+<% if (includePackageDocs) { %>
+
+## Removing Package Documentation
+This project includes package documentation for easier access to plugin documentation during development. If you want to remove this feature to reduce dependencies in production:
+
+1. **Remove package documentation plugins** from `docusaurus.config.ts`:
+   ```typescript
+   // Remove these plugin entries:
+   [
+     "@docusaurus/plugin-content-docs",
+     require("@sp-days-framework/docusaurus-plugin-interactive-tasks/publish-package-docs"),
+   ],
+   [
+     "@docusaurus/plugin-content-docs",
+     require("@sp-days-framework/docusaurus-plugin-slidev/publish-package-docs"),
+   ],
+   [
+     "@docusaurus/plugin-content-docs",
+     require("@sp-days-framework/docusaurus-frontpage-collection/publish-package-docs"),
+   ],
+   [
+     "@docusaurus/plugin-content-docs",
+     require("@sp-days-framework/slidev-theme-sykehuspartner/publish-package-docs"),
+   ],
+   [
+     "@docusaurus/plugin-content-docs",
+     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" },
+       { 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" },
+     ],
+   },
+   ```
+
+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
+   ```
+
+After these steps, the package documentation will no longer be included in your build, reducing the final bundle size.
+
+<% } %>

package/templates/page-course/docusaurus.config.ts

@@ -41,6 +41,7 @@ const config: Config = {
           id: "course",
           path: "course",
           routeBasePath: "course",
+          sidebarItemsGenerator: require('./sidebarSections'),
           beforeDefaultRemarkPlugins: [
             require("@sp-days-framework/docusaurus-plugin-interactive-tasks")
               .remarkTaskDirective,
@@ -60,6 +61,49 @@ const config: Config = {
     // Adds the Interactive Tasks plugin to enable task directives
     "@sp-days-framework/docusaurus-plugin-interactive-tasks",
 
+    // CONDITIONAL: package-docs (START)
+    // Interactive Tasks Plugin Documentation
+    [
+      "@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"),
+      },
+    ],
+    // CONDITIONAL: package-docs (END)
+
     // CONDITIONAL: addon-slidev (START)
     // Adds the Slidev plugin to enable slide presentations and static directories for Slidev assets
     "@sp-days-framework/docusaurus-plugin-slidev",
@@ -73,17 +117,7 @@ const config: Config = {
         id: "resources",
         path: "resources",
         routeBasePath: "resources",
-        beforeDefaultRemarkPlugins: [
-          [
-            require('@sp-days-framework/docusaurus-plugin-interactive-tasks')
-              .remarkTaskDirective,
-            {
-              // TOC configuration for resources docs instance
-              tocEnabled: true,
-              tocHeadingLevel: 3, // Use h2 for TOC entries (can be 2-6)
-            },
-          ],
-        ],
+        sidebarItemsGenerator: require('./sidebarSections'),
       },
     ],
     // CONDITIONAL: addon-resources (END)
@@ -120,6 +154,20 @@ const config: Config = {
         // CONDITIONAL: addon-slidev (START)
         { to: "/slidev", label: "Slides" },
         // CONDITIONAL: addon-slidev (END)
+        // CONDITIONAL: package-docs (START)
+        {
+          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" },
+          ],
+        },
+        // CONDITIONAL: package-docs (END)
         {
           href: gitRepositoryUrl,
           position: "right",

package/templates/page-course/package.json

@@ -12,6 +12,9 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
+    // CONDITIONAL: addon-slidev (START)
+    "slidev": "slidev",
+    // CONDITIONAL: addon-slidev (END)
     "typecheck": "tsc"
   },
   "dependencies": {
@@ -19,8 +22,15 @@
     "@docusaurus/preset-classic": "^3.9.2",
     "@docusaurus/theme-mermaid": "^3.9.2",
     "@mdx-js/react": "^3.0.0",
-    "@sp-days-framework/docusaurus-frontpage-collection": "^1.0.4",
-    "@sp-days-framework/docusaurus-plugin-interactive-tasks": "^1.0.4",
+    "@sp-days-framework/docusaurus-frontpage-collection": "^1.1.0-beta1",
+    "@sp-days-framework/docusaurus-plugin-interactive-tasks": "^1.1.0-beta1",
+    // CONDITIONAL: addon-slidev (START)
+    "@sp-days-framework/docusaurus-plugin-slidev": "^1.1.0-beta1",
+    "@sp-days-framework/slidev-theme-sykehuspartner": "^1.1.0-beta1",
+    // CONDITIONAL: addon-slidev (END)
+    // CONDITIONAL: package-docs (START)
+    "@sp-days-framework/create-sp-days": "^1.1.0-beta1",
+    // CONDITIONAL: package-docs (END)
     "clsx": "^2.0.0",
     "docusaurus-plugin-sass": "^0.2.6",
     "prism-react-renderer": "^2.3.0",