@learnpack/learnpack 5.0.277 → 5.0.279

package/src/utils/export/README.md

@@ -1,178 +1,178 @@
-# Export Utilities
-
-This directory contains utilities for exporting courses to different formats.
-
-## Supported Formats
-
-- **SCORM**: Learning Management System compatible package
-- **EPUB**: E-book format for offline reading
-
-## Usage
-
-### API Endpoints
-
-The export functionality is available through the `/export/:course_slug/:format` endpoint:
-
-- `GET /export/{course_slug}/scorm` - Export course to SCORM format
-- `GET /export/{course_slug}/epub` - Export course to EPUB format
-
-### Example Usage
-
-```bash
-# Export course to SCORM
-curl -O "http://localhost:3000/export/my-course/scorm"
-
-# Export course to EPUB (default English)
-curl -O "http://localhost:3000/export/my-course/epub"
-
-# Export course to EPUB in Spanish
-curl -O "http://localhost:3000/export/my-course/epub?language=es"
-
-# Export course to EPUB in French
-curl -O "http://localhost:3000/export/my-course/epub?language=fr"
-```
-
-## Requirements
-
-### SCORM Export
-
-- No additional requirements
-
-### EPUB Export
-
-- **Pandoc** must be installed on the system
-- Pandoc is used to convert markdown to HTML and generate EPUB files
-- **Language Support**: Use the `language` query parameter to specify the language
-  - Default: `en` (English)
-  - The system will prioritize language-specific files (e.g., `README.es.md` for Spanish)
-  - Falls back to `README.md` if no language-specific file is found
-
-### Installing Pandoc
-
-#### Windows
-
-```bash
-# Using Chocolatey
-choco install pandoc
-
-# Using Scoop
-scoop install pandoc
-
-# Or download from https://pandoc.org/installing.html
-```
-
-#### macOS
-
-```bash
-# Using Homebrew
-brew install pandoc
-
-# Using MacPorts
-sudo port install pandoc
-```
-
-#### Linux
-
-```bash
-# Ubuntu/Debian
-sudo apt-get install pandoc
-
-# CentOS/RHEL
-sudo yum install pandoc
-
-# Arch Linux
-sudo pacman -S pandoc
-```
-
-## Architecture
-
-The export system is modular and consists of:
-
-- **`types.ts`**: Type definitions for export options and course metadata
-- **`shared.ts`**: Common utility functions used by all export formats
-- **`scorm.ts`**: SCORM export implementation
-- **`epub.ts`**: EPUB export implementation using Pandoc
-- **`index.ts`**: Main export interface
-
-## Adding New Export Formats
-
-To add a new export format:
-
-1. Create a new file in the export directory (e.g., `pdf.ts`)
-2. Implement the export function following the same pattern
-3. Add the new format to the `ExportFormat` type in `types.ts`
-4. Update the main export endpoint in `serve.ts`
-5. Add the new format to the export index
-
-### Example New Format
-
-```typescript
-// pdf.ts
-export async function exportToPdf(options: ExportOptions): Promise<string> {
-  // Implementation here
-  return outputPath;
-}
-
-// types.ts
-export type ExportFormat = 'scorm' | 'epub' | 'pdf';
-
-// serve.ts
-} else if (format === "pdf") {
-  outputPath = await exportToPdf({
-    courseSlug: course_slug,
-    format: "pdf",
-    bucket,
-    outDir: path.join(__dirname, "../output/directory")
-  });
-  filename = `${course_slug}.pdf`;
-}
-```
-
-## File Structure
-
-```
-src/utils/export/
-├── index.ts          # Main export interface
-├── types.ts          # Type definitions
-├── shared.ts         # Shared utilities
-├── scorm.ts          # SCORM export
-├── epub.ts           # EPUB export
-├── templates/        # Export templates
-│   ├── scorm/        # SCORM template files
-│   └── epub/         # EPUB template files
-└── README.md         # This file
-```
-
-## Templates
-
-### SCORM Template
-
-Contains the necessary files for a SCORM package:
-
-- `imsmanifest.xml` - Course manifest
-- `config/` - Configuration files
-- XSD schema files for validation
-
-### EPUB Template
-
-Contains styling and assets for EPUB generation:
-
-- `epub.css` - Basic EPUB styling
-- `cover.png` - Default cover image (placeholder)
-
-## Error Handling
-
-The export system includes comprehensive error handling:
-
-- Invalid format validation
-- File system operation errors
-- Pandoc execution errors (for EPUB)
-- Network/download errors
-- Cleanup on failure
-
-## Performance Considerations
-
-- Temporary files are automatically cleaned up
-- Large courses may take time to process
-- Consider implementing progress indicators for long-running exports
-- Memory usage scales with course size
+# Export Utilities
+
+This directory contains utilities for exporting courses to different formats.
+
+## Supported Formats
+
+- **SCORM**: Learning Management System compatible package
+- **EPUB**: E-book format for offline reading
+
+## Usage
+
+### API Endpoints
+
+The export functionality is available through the `/export/:course_slug/:format` endpoint:
+
+- `GET /export/{course_slug}/scorm` - Export course to SCORM format
+- `GET /export/{course_slug}/epub` - Export course to EPUB format
+
+### Example Usage
+
+```bash
+# Export course to SCORM
+curl -O "http://localhost:3000/export/my-course/scorm"
+
+# Export course to EPUB (default English)
+curl -O "http://localhost:3000/export/my-course/epub"
+
+# Export course to EPUB in Spanish
+curl -O "http://localhost:3000/export/my-course/epub?language=es"
+
+# Export course to EPUB in French
+curl -O "http://localhost:3000/export/my-course/epub?language=fr"
+```
+
+## Requirements
+
+### SCORM Export
+
+- No additional requirements
+
+### EPUB Export
+
+- **Pandoc** must be installed on the system
+- Pandoc is used to convert markdown to HTML and generate EPUB files
+- **Language Support**: Use the `language` query parameter to specify the language
+  - Default: `en` (English)
+  - The system will prioritize language-specific files (e.g., `README.es.md` for Spanish)
+  - Falls back to `README.md` if no language-specific file is found
+
+### Installing Pandoc
+
+#### Windows
+
+```bash
+# Using Chocolatey
+choco install pandoc
+
+# Using Scoop
+scoop install pandoc
+
+# Or download from https://pandoc.org/installing.html
+```
+
+#### macOS
+
+```bash
+# Using Homebrew
+brew install pandoc
+
+# Using MacPorts
+sudo port install pandoc
+```
+
+#### Linux
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install pandoc
+
+# CentOS/RHEL
+sudo yum install pandoc
+
+# Arch Linux
+sudo pacman -S pandoc
+```
+
+## Architecture
+
+The export system is modular and consists of:
+
+- **`types.ts`**: Type definitions for export options and course metadata
+- **`shared.ts`**: Common utility functions used by all export formats
+- **`scorm.ts`**: SCORM export implementation
+- **`epub.ts`**: EPUB export implementation using Pandoc
+- **`index.ts`**: Main export interface
+
+## Adding New Export Formats
+
+To add a new export format:
+
+1. Create a new file in the export directory (e.g., `pdf.ts`)
+2. Implement the export function following the same pattern
+3. Add the new format to the `ExportFormat` type in `types.ts`
+4. Update the main export endpoint in `serve.ts`
+5. Add the new format to the export index
+
+### Example New Format
+
+```typescript
+// pdf.ts
+export async function exportToPdf(options: ExportOptions): Promise<string> {
+  // Implementation here
+  return outputPath;
+}
+
+// types.ts
+export type ExportFormat = 'scorm' | 'epub' | 'pdf';
+
+// serve.ts
+} else if (format === "pdf") {
+  outputPath = await exportToPdf({
+    courseSlug: course_slug,
+    format: "pdf",
+    bucket,
+    outDir: path.join(__dirname, "../output/directory")
+  });
+  filename = `${course_slug}.pdf`;
+}
+```
+
+## File Structure
+
+```
+src/utils/export/
+├── index.ts          # Main export interface
+├── types.ts          # Type definitions
+├── shared.ts         # Shared utilities
+├── scorm.ts          # SCORM export
+├── epub.ts           # EPUB export
+├── templates/        # Export templates
+│   ├── scorm/        # SCORM template files
+│   └── epub/         # EPUB template files
+└── README.md         # This file
+```
+
+## Templates
+
+### SCORM Template
+
+Contains the necessary files for a SCORM package:
+
+- `imsmanifest.xml` - Course manifest
+- `config/` - Configuration files
+- XSD schema files for validation
+
+### EPUB Template
+
+Contains styling and assets for EPUB generation:
+
+- `epub.css` - Basic EPUB styling
+- `cover.png` - Default cover image (placeholder)
+
+## Error Handling
+
+The export system includes comprehensive error handling:
+
+- Invalid format validation
+- File system operation errors
+- Pandoc execution errors (for EPUB)
+- Network/download errors
+- Cleanup on failure
+
+## Performance Considerations
+
+- Temporary files are automatically cleaned up
+- Large courses may take time to process
+- Consider implementing progress indicators for long-running exports
+- Memory usage scales with course size