create-marp-presentation 1.2.0 → 1.2.2

package/docs/theme-management.md

@@ -0,0 +1,261 @@
+# Theme Management Guide
+
+This guide explains how to use the theme management system in your Marp presentation project.
+
+## Overview
+
+The theme management system provides a simple way to:
+- Add pre-built themes to your project
+- List available and installed themes
+- Switch between themes
+- Create custom themes
+- Integrate with VSCode for live preview
+
+## Available Themes
+
+The following themes are available in the template:
+
+- **beam** - Clean, modern theme with progress bar
+- **default-clean** - Minimal variation of default theme
+- **gaia-dark** - Dark version of the Gaia theme
+- **marpx** - Extended version of Marp's default theme
+- **socrates** - Educational theme with clear typography
+- **uncover-minimal** - Minimal reveal-style theme
+
+### System Themes
+
+These built-in Marp themes are always available:
+- **default** - Marp's default theme
+- **gaia** - Clean, professional theme
+- **uncover** - Slide-by-slide reveal theme
+
+## Commands
+
+### List Themes
+
+```bash
+npm run theme:list
+```
+
+This shows:
+- Available themes in the theme library
+- Installed themes in your project's `themes/` directory
+- Dependencies for each theme
+
+### Add Themes
+
+```bash
+npm run theme:add
+```
+
+You'll be prompted to:
+1. Select themes from the available list
+2. Resolve any conflicts (if themes with the same name exist)
+3. Confirm the selection
+
+The command will:
+- Copy theme files to your `themes/` directory
+- Resolve dependencies automatically
+- Update VSCode settings
+- Skip themes that would conflict (unless using `--force`)
+
+**Options:**
+```bash
+npm run theme add --force      # Overwrite existing themes
+npm run theme add --no-vscode  # Skip VSCode settings update
+```
+
+### Set Active Theme
+
+```bash
+npm run theme:set <theme-name>
+```
+
+This will:
+- Update the `theme` value in `presentation.md` frontmatter
+- Add the theme to VSCode settings (for custom themes)
+- Warn if the theme is not installed
+
+**Examples:**
+```bash
+npm run theme:set beam
+npm run theme:set default
+npm run theme:set gaia
+```
+
+### Create Custom Theme
+
+```bash
+npm run theme:create <theme-name>
+```
+
+You'll be prompted to:
+1. Select a parent theme to base your theme on
+2. Choose a directory location (root, subfolder, or new folder)
+
+The command will:
+- Create a new CSS file in the appropriate location
+- Add the theme directive and parent import
+- Update VSCode settings if needed
+
+**Example:**
+```bash
+npm run theme:create my-brand
+# Select parent: beam
+# Select location: root
+# Creates: themes/my-brand.css
+```
+
+## Theme File Structure
+
+Themes are organized in the `themes/` directory:
+
+```
+my-presentation/
+├── themes/
+│   ├── beam.css
+│   ├── marpx.css
+│   └── custom/
+│       └── my-theme.css
+└── presentation.md
+```
+
+### Theme File Format
+
+Each theme CSS file must include:
+1. A theme directive: `/* @theme theme-name */`
+2. Optional parent imports: `@import "parent-theme";`
+
+**Example:**
+```css
+/* @theme my-custom */
+@import "beam";
+
+:root {
+  --color-primary: #3498db;
+  --color-secondary: #2ecc71;
+}
+
+section {
+  background: linear-gradient(135deg, var(--color-primary), var(--color-secondary));
+}
+```
+
+## VSCode Integration
+
+The theme management system automatically updates VSCode settings for live preview support.
+
+### Settings Location
+
+`.vscode/settings.json`:
+```json
+{
+  "markdown.marp.themes": [
+    "themes/beam/beam.css",
+    "themes/marpx/marpx.css"
+  ]
+}
+```
+
+### How It Works
+
+- When you add themes, they're added to the settings
+- When you set an active theme, it's added to the settings
+- System themes (default, gaia, uncover) are not added (built-in)
+- Use `--no-vscode` to skip this behavior
+
+## Manual Theme Management
+
+You can also manage themes manually:
+
+### Add a Theme Manually
+
+1. Copy your theme CSS file to the `themes/` directory (e.g., `themes/your-theme/your-theme.css`)
+2. Add the theme directive: `/* @theme your-theme-name */`
+3. Update `.vscode/settings.json` if needed:
+   ```json
+   {
+     "markdown.marp.themes": ["themes/your-theme/your-theme.css"]
+   }
+   ```
+
+### Switch Theme Manually
+
+Edit `presentation.md`:
+```yaml
+---
+marp: true
+theme: your-theme-name
+---
+```
+
+## Troubleshooting
+
+### Theme Not Found
+
+If you get a "Theme not found" error:
+1. Check if the theme is installed: `npm run theme:list`
+2. Add the theme if missing: `npm run theme:add`
+3. Verify the theme name matches exactly
+
+### Live Preview Not Working
+
+If VSCode live preview doesn't show your theme:
+1. Check `.vscode/settings.json` exists
+2. Verify the theme path is correct
+3. Reload the VSCode window
+
+### Dependencies Not Found
+
+Warning about missing dependencies is expected for system themes (default, gaia, uncover). These are built into Marp CLI and don't need to be in your project.
+
+## Best Practices
+
+1. **Use Descriptive Names**: Name themes clearly (e.g., `brand-primary`, `presentation-dark`)
+2. **Organize Themes**: Use subfolders for many themes
+3. **Document Dependencies**: Include parent theme imports in comments
+4. **Test Themes**: Always test with `npm run dev` after changing themes
+5. **Version Control**: Commit your custom themes to git
+
+## Advanced Usage
+
+### Creating Theme Variants
+
+Create multiple variants based on the same parent:
+
+```bash
+npm run theme:create brand-light  # Parent: beam
+npm run theme:create brand-dark   # Parent: beam
+```
+
+Edit the themes to differentiate them:
+
+```css
+/* themes/brand-light.css */
+/* @theme brand-light */
+@import "beam";
+:root { --bg-color: #ffffff; }
+
+/* themes/brand-dark.css */
+/* @theme brand-dark */
+@import "beam";
+:root { --bg-color: #1a1a1a; }
+```
+
+### Conditional Themes
+
+Use different themes for different presentations:
+
+```bash
+# For external presentations
+npm run theme:set brand-professional
+
+# For internal workshops
+npm run theme:set brand-casual
+```
+
+## References
+
+- [Marp Theme Documentation](https://marp.app/docs/theming)
+- [Marp CLI GitHub](https://github.com/marp-team/marp-cli)
+- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)

package/lib/add-themes-command.js

@@ -319,7 +319,11 @@ class AddThemesCommand {
     if (result === 'overwrite-all') return { overwrite: conflicts };
     if (result === 'cancel') return { overwrite: [] };
 
-    // Handle 'choose-each' or individual conflicts
+    // Handle single conflict responses
+    if (result === 'skip') return { overwrite: [] };
+    if (result === 'overwrite') return { overwrite: conflicts };
+
+    // Handle 'choose-each' - prompt for each conflict individually
     const overwrite = [];
     for (const conflict of conflicts) {
       const choice = await Prompts.promptSingleConflict(conflict);

package/lib/prompts.js

@@ -17,11 +17,16 @@ class Prompts {
       return [];
     }
 
-    const choices = availableThemes.map(theme => ({
-      name: theme.name,
-      value: theme.name,
-      checked: false
-    }));
+    const choices = availableThemes.map(theme => {
+      const displayName = theme.description
+        ? `${theme.name} - ${theme.description}`
+        : theme.name;
+      return {
+        name: displayName,
+        value: theme.name,
+        checked: false
+      };
+    });
 
     return await inquirer.checkbox({
       message: 'Select themes to add:',
@@ -152,6 +157,18 @@ class Prompts {
     });
   }
 
+  /**
+   * Prompt user for new theme description
+   *
+   * @returns {Promise<string|null>} Theme description or null if skipped
+   */
+  static async promptNewThemeDescription() {
+    return await inquirer.input({
+      message: 'Theme description (optional - press Enter to skip):',
+      default: ''
+    });
+  }
+
   /**
    * Prompt user for conflict resolution
    *

package/lib/theme-manager.js

@@ -4,6 +4,7 @@ const path = require('path');
 const { ThemeResolver } = require('./theme-resolver');
 const { VSCodeIntegration } = require('./vscode-integration');
 const { Frontmatter } = require('./frontmatter');
+const { Prompts } = require('./prompts');
 const {
   ThemeNotFoundError,
   ThemeAlreadyExistsError,
@@ -173,10 +174,11 @@ class ThemeManager {
    * @param {string|null} parent - Parent theme name or null
    * @param {string} location - 'root', 'existing' folder name, or 'new'
    * @param {string} newFolderName - Required if location is 'new'
+   * @param {string|null} description - Optional theme description
    * @throws {ThemeAlreadyExistsError} If theme with same name already exists
    * @throws {Error} If location is 'new' but newFolderName not provided
    */
-  createTheme(name, parent, location, newFolderName = null) {
+  createTheme(name, parent, location, newFolderName = null, description = null) {
     // Check for duplicate
     if (this.getTheme(name)) {
       throw new ThemeAlreadyExistsError(name);
@@ -198,7 +200,11 @@ class ThemeManager {
     }
 
     // Generate CSS content
-    let css = `/* @theme ${name} */\n\n`;
+    let css = `/* @theme ${name}`;
+    if (description && description.trim()) {
+      css += `\n * @description ${description.trim()}`;
+    }
+    css += ` */\n\n`;
 
     if (parent) {
       css += `@import "${parent}";\n\n`;

package/lib/theme-resolver.js

@@ -7,11 +7,12 @@ const path = require('path');
  * Represents a Marp theme
  */
 class Theme {
-  constructor(name, cssPath, css, dependencies = []) {
+  constructor(name, cssPath, css, dependencies = [], description = null) {
     this.name = name;
     this.path = cssPath;
     this.css = css;
     this.dependencies = dependencies;
+    this.description = description;
     this.isSystem = ['default', 'gaia', 'uncover'].includes(name);
   }
 }
@@ -81,6 +82,22 @@ class ThemeResolver {
     return dependencies;
   }
 
+  /**
+   * Extract @description from CSS comment directive
+   * Pattern: /* @description text *\/
+   *
+   * @param {string} cssContent - CSS file content
+   * @returns {string|null} Description text or null if not found
+   */
+  static extractDescription(cssContent) {
+    // Match /* @description text */ - supports multi-line comments
+    // The [\s\S]*? allows matching across newlines (non-greedy)
+    const descRegex = /\/\*[\s\S]*?@description\s+([^\r\n*]+)[\s\S]*?\*\//;
+    const match = cssContent.match(descRegex);
+
+    return match ? match[1].trim() : null;
+  }
+
   /**
    * Resolve theme from a CSS file
    *
@@ -97,8 +114,9 @@ class ThemeResolver {
     const filename = path.basename(cssPath);
     const name = this.extractThemeName(css, filename) || filename;
     const dependencies = this.extractDependencies(css);
+    const description = this.extractDescription(css);
 
-    return new Theme(name, cssPath, css, dependencies);
+    return new Theme(name, cssPath, css, dependencies, description);
   }
 
   /**

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "create-marp-presentation",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Create a new Marp presentation project with one command. Manage themes quickly and easily with the CLI.",
   "bin": {
     "create-marp-presentation": "index.js"
   },
   "files": [
     "index.js",
+    "cli/",
     "lib/",
+    "docs/",
     "template/",
     "template-optional/",
     "themes/"

package/themes/beam/beam.css

@@ -1,4 +1,5 @@
 /* @theme beam */
+/* @description Beamer-inspired theme with clean headers and footer bars */
 /* Author: rnd195 https://github.com/rnd195/ */
 /* beam license - GNU GPLv3 https://github.com/rnd195/my-marp-themes/blob/live/licenses/LICENSE_beam */
 /* License of beamer which inspired this theme - GNU GPLv2 https://github.com/rnd195/my-marp-themes/blob/live/licenses/LICENSE_GPLv2 */

package/themes/default-clean/default-clean.css

@@ -1,5 +1,5 @@
 /* @theme default-clean */
-/* A clean, minimal theme based on default */
+/* @description A clean, minimal theme based on default */
 
 @import "default";
 

package/themes/gaia-dark/gaia-dark.css

@@ -1,5 +1,5 @@
 /* @theme gaia-dark */
-/* A dark variant of the gaia theme */
+/* @description A dark variant of the gaia theme */
 
 @import "gaia";
 

package/themes/marpx/marpx.css

@@ -31,8 +31,9 @@
 *
 * ================================================================================ */
 
-/* 
+/*
 * @theme marpx
+* @description Modern multi-format theme with auto-scaling support
 *
 * @auto-scaling true
 * @size 16:9 1280px 720px

package/themes/marpx/socrates.css

@@ -1,4 +1,5 @@
 /* @theme socrates */
+/* @description A classic teaching theme based on marpx */
 
 @import "marpx";
 

package/themes/uncover-minimal/uncover-minimal.css

@@ -1,5 +1,5 @@
 /* @theme uncover-minimal */
-/* A minimal variant of the uncover theme */
+/* @description A minimal variant of the uncover theme */
 
 @import "uncover";