portapack 0.2.1 → 0.3.1

package/docs/.vitepress/config.ts

@@ -48,7 +48,6 @@ export default defineConfig({
           { text: 'Advanced Usage', link: '/advanced' }
         ]
       },
-      { text: 'Demo', link: '/demo' },
       { text: 'Contributing', link: '/contributing' }
     ],
 

package/docs/cli.md

@@ -1,117 +1,180 @@
-# ⚙️ CLI Reference
+# ⚙️ PortaPack CLI Reference
 
-PortaPack provides a powerful command-line interface for bundling HTML files and websites.
+PortaPack provides a powerful command-line interface (CLI) for bundling local HTML files and remote websites into single, portable HTML files.
 
 ## Installation
 
-To use the CLI, install PortaPack globally:
+To use the CLI, install PortaPack globally using npm (or your preferred package manager):
 
 ```bash
 npm install -g portapack
+# or
+# yarn global add portapack
+# or
+# pnpm add -g portapack
 ```
 
 ## Command Syntax
 
-The basic command structure is:
+The basic syntax for the PortaPack CLI is:
 
 ```bash
-portapack [options]
+portapack [input] [options]
 ```
 
+Where `[input]` is the path to a local HTML file or a remote URL.
+
 ## Options
 
 | Option | Shorthand | Description | Default |
-|--------|----------|------------|---------|
-| `--input <path>` | `-i` | Input file or URL to process | - |
-| `--output <file>` | `-o` | Output file path | `{input}.packed.html` |
-| `--minify [level]` | `-m` | Minification level (0-3) | `2` |
-| `--no-minify` | - | Disable minification | - |
-| `--recursive [depth]` | `-r` | Recursively bundle links up to specified depth | - |
-| `--base-url <url>` | `-b` | Base URL for resolving relative URLs | - |
-| `--dry-run` | `-d` | Show what would be done without writing files | - |
-| `--verbose` | `-v` | Enable verbose logging | - |
-| `--help` | `-h` | Show help information | - |
-| `--version` | - | Show version information | - |
+|--------|-----------|-------------|---------|
+| `[input]` | | Required. Input local file path or remote URL (http/https) to process. | - |
+| `--output <file>` | `-o` | Output file path for the bundled HTML. | `{input-basename}.packed.html` |
+| `--recursive [depth]` | `-r` | Recursively bundle links up to depth. If depth omitted, defaults to true (no limit). Only applies to remote URLs. | `false` (disabled) |
+| `--max-depth <n>` | | Set maximum depth for recursive crawling (alternative to `-r <n>`). | - |
+| `--minify` | `-m` | Enable all minification (HTML, CSS, JS). | - |
+| `--no-minify` | | Disable all asset minification (HTML, CSS, JS). | `false` |
+| `--no-minify-html` | | Disable only HTML minification. | `false` |
+| `--no-minify-css` | | Disable only CSS minification. | `false` |
+| `--no-minify-js` | | Disable only JavaScript minification. | `false` |
+| `--embed-assets` | `-e` | Embed external assets (CSS, JS, images, fonts) as data URIs or inline content. | `true` |
+| `--no-embed-assets` | | Keep external assets as links (requires network access when viewing). | `false` |
+| `--base-url <url>` | `-b` | Base URL for resolving relative URLs found in the input HTML. | Input path/URL |
+| `--log-level <level>` | | Set logging level (debug, info, warn, error, silent, none). | `info` |
+| `--verbose` | `-v` | Enable verbose logging (shortcut for `--log-level debug`). | `false` |
+| `--dry-run` | `-d` | Perform all steps except writing the output file. Logs intended actions. | `false` |
+| `--help` | `-h` | Show help information and exit. | - |
+| `--version` | | Show PortaPack CLI version number and exit. | - |
 
 ## Examples
 
-### Basic Usage
+### Basic Local File Bundling
+
+Bundle `index.html` into `bundle.html`:
+
+```bash
+portapack ./index.html -o bundle.html
+```
 
-Bundle a local HTML file:
+Use default output name (`index.packed.html`):
 
 ```bash
-portapack -i ./index.html -o bundle.html
+portapack ./index.html
 ```
 
 ### Web Page Bundling
 
-Bundle a remote website:
+Bundle a single remote webpage:
 
 ```bash
-portapack -i https://example.com -o example-bundle.html
+portapack https://example.com -o example-bundle.html
 ```
 
 ### Recursive Bundling
 
-Bundle a website and follow its links to a depth of 2:
+Bundle a website, following links 1 level deep:
+
+```bash
+portapack https://example.com -r -o site-bundle-depth1.html
+```
+
+Bundle a website, following links up to 2 levels deep:
+
+```bash
+portapack https://example.com -r 2 -o site-bundle-depth2.html
+```
+
+Alternative using `--max-depth` option:
+
+```bash
+portapack https://example.com --max-depth 2 -o site-bundle-depth2.html
+```
+
+### Asset Handling
+
+Bundle without embedding assets (keep external links):
+
+```bash
+portapack ./index.html --no-embed-assets -o linked-assets.html
+```
+
+Default behavior is to embed assets (which you can make explicit):
 
 ```bash
-portapack -i https://example.com -r 2 -o site-bundle.html
+portapack ./index.html --embed-assets -o embedded-assets.html
 ```
 
 ### Minification Control
 
-Apply maximum minification:
+Apply all minification:
+
+```bash
+portapack ./index.html -m -o min-bundle.html
+```
+
+Disable minification completely:
 
 ```bash
-portapack -i ./index.html -m 3 -o min-bundle.html
+portapack ./index.html --no-minify -o unmin-bundle.html
 ```
 
-Disable minification:
+Selectively control minification:
 
 ```bash
-portapack -i ./index.html --no-minify -o unmin-bundle.html
+# Minify CSS and JS but not HTML
+portapack ./index.html --no-minify-html -o selective-min.html
+
+# Minify HTML and CSS but not JS
+portapack ./index.html --no-minify-js -o no-js-min.html
 ```
 
 ### Base URL for Relative Links
 
-Specify a base URL for resolving relative paths:
+Process a local file as if it were hosted at https://example.com:
 
 ```bash
-portapack -i ./index.html -b https://example.com -o bundle.html
+portapack ./docs/index.html -b https://example.com/docs/ -o bundle.html
+```
+
+### Logging and Debugging
+
+Enable detailed debug logs:
+
+```bash
+portapack ./index.html -v -o bundle-debug.html
+```
+
+Only show errors:
+
+```bash
+portapack ./index.html --log-level error -o bundle-errors-only.html
 ```
 
 ### Dry Run
 
-Preview what would be bundled without creating an output file:
+See what files and assets would be processed without saving:
 
 ```bash
-portapack -i ./index.html --dry-run
+portapack ./index.html --dry-run
 ```
 
-### Verbose Logging
+### NPX Usage
 
-Enable detailed logs during bundling:
+Use PortaPack without installing globally:
 
 ```bash
-portapack -i ./index.html -v -o bundle.html
+npx portapack ./index.html -o bundle.html
 ```
 
 ## Exit Codes
 
 | Code | Description |
 |------|-------------|
-| `0` | Success |
-| `1` | Error (missing input, invalid URL, processing error, etc.) |
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `NODE_ENV` | Set to `test` during testing to suppress console output |
+| 0 | Success |
+| 1 | Error |
 
 ## Related Resources
 
-- [Getting Started](/getting-started)
-- [API Reference](/api/README)
-- [Configuration Guide](/configuration)
+- [Getting Started](https://manicinc.github.io/portapack/getting-started)
+- [API Reference](https://manicinc.github.io/portapack/api/)
+- [Configuration Guide](https://manicinc.github.io/portapack/configuration)

package/docs/configuration.md

@@ -1,151 +1,136 @@
-# 🛠 PortaPack Configuration Guide
+# 🚀 Getting Started with PortaPack
 
-## 📝 Configuration Options
+## Prerequisites
 
-PortaPack provides multiple ways to configure its behavior:
+- Node.js (v16.0.0+)
+- npm (v8.0.0+)
 
-### CLI Configuration
+## Quick Installation
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `-i, --input` | String | Required | Input HTML file or URL |
-| `-o, --output` | String | `{input}.packed.html` | Output file path |
-| `-m, --minify` | Number | `2` | Minification level (0-3) |
-| `--no-minify` | Flag | - | Disable minification |
-| `-r, --recursive` | Boolean/Number | `false` | Crawl site recursively, optionally with depth |
-| `-b, --base-url` | String | Detected | Base URL for resolving paths |
-| `-d, --dry-run` | Flag | `false` | Preview without generating output |
-| `-v, --verbose` | Flag | `false` | Enable verbose logging |
-
-### Programmatic Configuration
-
-```typescript
-// Simple string input
-await generatePortableHTML('./index.html');
-
-// With options as second parameter
-await generatePortableHTML('./index.html', {
-  minify: true,
-  minifyLevel: 2,
-  baseUrl: 'https://example.com'
-});
+```bash
+# Global installation
+npm install -g portapack
 
-// Or with options object
-await generatePortableHTML({
-  input: './index.html',
-  minify: true,
-  minifyLevel: 2,
-  baseUrl: 'https://example.com',
-  
-  // Asset handling
-  embedAssets: true,
-  embedLimit: 1000000,
-  
-  // Minification controls
-  minifyHtml: true,
-  minifyCss: true,
-  minifyJs: true,
-  
-  // Advanced options
-  removeComments: true,
-  collapseWhitespace: true
-});
+# Or as a project dependency
+npm install --save-dev portapack
 ```
 
-## 🔧 Configuration Examples
+## Basic Usage
 
-### CLI Configuration
+### CLI Quickstart
 
 ```bash
-# Basic usage
-portapack -i ./index.html -o bundled.html
-
-# Maximum minification
-portapack -i ./site -m 3 -o min.html
+# Bundle a local HTML file
+portapack ./index.html -o portable.html
 
-# Disable minification
-portapack -i ./site --no-minify
+# Bundle a remote website
+portapack https://example.com --recursive -o site.html
+```
 
-# Set custom base URL
-portapack -i ./local/site -b https://example.com
+### Node.js API Basic Example
 
-# Recursive crawling with depth
-portapack -i https://site.com -r 2
+```typescript
+import { pack } from 'portapack';
 
-# Dry run to preview
-portapack -i https://example.com --dry-run -v
+// Simple usage with a string path
+async function bundleLocalSite() {
+  const result = await pack('./index.html');
+  console.log(result.html);
+  
+  // Access metadata about the build
+  console.log(`Output size: ${result.metadata.outputSize} bytes`);
+  console.log(`Build time: ${result.metadata.buildTimeMs} ms`);
+}
+
+// Advanced options using configuration object
+async function bundleWithOptions() {
+  const result = await pack('./index.html', {
+    minifyHtml: true,
+    minifyCss: true,
+    minifyJs: true,
+    baseUrl: 'https://example.com',
+    embedAssets: true
+  });
+ 
+  // Use or save the bundled HTML
+  console.log(result.html);
+}
+
+// Recursive bundling of a website
+async function bundleWebsite() {
+  const result = await pack('https://example.com', {
+    recursive: 2,  // Crawl up to 2 levels deep
+    minifyHtml: true,
+    minifyCss: true,
+    minifyJs: true
+  });
+  
+  console.log(`Bundled ${result.metadata.pagesBundled} pages`);
+}
 ```
 
-### Programmatic Configuration
+### Advanced API Usage
+
+For more specific use cases, you can access individual components:
 
 ```typescript
-// Basic local file
-const html = await generatePortableHTML('index.html');
-
-// Remote URL with minification options
-const html = await generatePortableHTML({
-  input: 'https://example.com',
-  minify: true,
-  minifyLevel: 3,
-  removeComments: true
+import {
+  generatePortableHTML,
+  generateRecursivePortableHTML,
+  bundleMultiPageHTML,
+  fetchAndPackWebPage,
+} from 'portapack';
+
+// Bundle a single HTML file or URL
+const singleResult = await generatePortableHTML('./index.html', {
+  minifyHtml: true
 });
 
-// With custom base URL
-const html = await generatePortableHTML({
-  input: './index.html',
-  baseUrl: 'https://example.com',
-  embedAssets: true
+// Recursively bundle a site
+const recursiveResult = await generateRecursivePortableHTML('https://example.com', 2, {
+  minifyCss: true
 });
 
-// Recursive site bundling
-await bundleSiteRecursively(
-  'https://example.com',
-  'output.html',
-  2 // Depth
-);
+// Create multi-page bundle
+const multiPageBundle = await bundleMultiPageHTML([
+  { path: '/', html: '<html>...</html>' },
+  { path: '/about', html: '<html>...</html>' }
+]);
 ```
 
-## 💡 Best Practices
+## Configuration
 
-- **Base URL Handling**: Always specify a `baseUrl` when working with relative paths
-- **Asset Size**: Be mindful of embedding large assets; use `embedLimit` to set thresholds
-- **Minification Levels**: Start with level 2 and adjust based on needs:
-  - Level 0: No minification
-  - Level 1: Basic whitespace removal
-  - Level 2: Standard minification (recommended)
-  - Level 3: Aggressive minification (may affect readability)
-- **Testing**: Use `--dry-run -v` to preview configuration without generating files
-- **Performance**: For large sites, increase Node's memory limit with `NODE_OPTIONS=--max-old-space-size=4096`
+See our full [Configuration Guide](https://manicinc.github.io/portapack/configuration) for detailed options.
+
+## CLI Options
+
+PortaPack offers many command-line options for customizing the bundling process:
+
+```bash
+# Get full help
+portapack --help
+```
 
-## 🚨 Configuration Warnings
+For details, see the [CLI Reference](https://manicinc.github.io/portapack/cli).
 
-- Deep recursive crawling can be resource-intensive
-- Large sites may require increased memory allocation
-- Some asset embedding might fail with complex dynamic sites
-- External scripts with CORS restrictions may not embed properly
+## Next Steps
 
-## 📂 File Types Supported
+- 📖 [Explore CLI Options](https://manicinc.github.io/portapack/cli)
+- 🛠 [Advanced Configuration](https://manicinc.github.io/portapack/configuration)
+- 💻 [API Reference](https://manicinc.github.io/portapack/api/)
 
-PortaPack automatically detects and processes:
+## Troubleshooting
 
-- **HTML files**: Main content files
-- **CSS stylesheets**: Both inline and external
-- **JavaScript**: Script files and inline scripts
-- **Images**: PNG, JPEG, GIF, SVG, WebP (converted to data URLs)
-- **Fonts**: WOFF, WOFF2, TTF, EOT (embedded)
-- **Other assets**: PDFs, JSON, text files, etc.
+Encountering issues? Check our [Troubleshooting Guide](https://manicinc.github.io/portapack/troubleshooting)
 
-## 🔄 Environment Variables
+## Contributing
 
-PortaPack also supports configuration via environment variables:
+Interested in improving PortaPack?
+- [View Contributing Guidelines](https://manicinc.github.io/portapack/contributing)
 
-- `PORTAPACK_BASE_URL`: Sets the base URL
-- `PORTAPACK_MINIFY_LEVEL`: Sets minification level
-- `PORTAPACK_NO_EMBED`: Disables asset embedding when set to "true"
+## Support
 
-## 📚 Related Documentation
+- 🐛 [Report an Issue](https://github.com/manicinc/portapack/issues)
+- 💬 [Community Support](https://discord.gg/DzNgXdYm)
 
-- [CLI Reference](/cli)
-- [API Reference](/api/README)
-- [Getting Started Guide](/getting-started)
-- [Troubleshooting](/troubleshooting)
+Built by [Manic.agency](https://manic.agency)

package/docs/getting-started.md

@@ -15,88 +15,118 @@ npm install -g portapack
 npm install --save-dev portapack
 ```
 
-## Documentation
-
-Our documentation is automatically generated and hosted locally:
-
-- 🌐 **Local Docs**: at `http://localhost:5173`
-- 📦 **Auto-Generated API Docs**: Dynamically created from TypeDoc comments
-- 🧩 **Sidebar Generation**: Intelligent, automated sidebar creation
-
-### Running Documentation Locally
-
-```bash
-# Start documentation development server
-npm run docs:dev
-```
-
 ## Basic Usage
 
 ### CLI Quickstart
 
 ```bash
 # Bundle a local HTML file
-portapack -i ./index.html -o portable.html
+portapack ./index.html -o portable.html
 
 # Bundle a remote website
-portapack -i https://example.com --recursive -o site.html
+portapack https://example.com --recursive -o site.html
 ```
 
 ### Node.js API Basic Example
 
 ```typescript
-import { generatePortableHTML } from 'portapack';
+import { pack } from 'portapack';
 
 // Simple usage with a string path
 async function bundleLocalSite() {
-  const portableHtml = await generatePortableHTML('./index.html');
-  console.log(portableHtml);
+  const result = await pack('./index.html');
+  console.log(result.html);
+  
+  // Access metadata about the build
+  console.log(`Output size: ${result.metadata.outputSize} bytes`);
+  console.log(`Build time: ${result.metadata.buildTimeMs} ms`);
 }
 
 // Advanced options using configuration object
 async function bundleWithOptions() {
-  const portableHtml = await generatePortableHTML({
-    input: './index.html',
-    minify: true,
-    minifyLevel: 2,
-    baseUrl: 'https://example.com'
+  const result = await pack('./index.html', {
+    minifyHtml: true,
+    minifyCss: true,
+    minifyJs: true,
+    baseUrl: 'https://example.com',
+    embedAssets: true
   });
-  
+ 
   // Use or save the bundled HTML
-  console.log(portableHtml);
+  console.log(result.html);
 }
+
+// Recursive bundling of a website
+async function bundleWebsite() {
+  const result = await pack('https://example.com', {
+    recursive: 2,  // Crawl up to 2 levels deep
+    minifyHtml: true,
+    minifyCss: true,
+    minifyJs: true
+  });
+  
+  console.log(`Bundled ${result.metadata.pagesBundled} pages`);
+}
+```
+
+### Advanced API Usage
+
+For more specific use cases, you can access individual components:
+
+```typescript
+import {
+  generatePortableHTML,
+  generateRecursivePortableHTML,
+  bundleMultiPageHTML,
+  fetchAndPackWebPage,
+} from 'portapack';
+
+// Bundle a single HTML file or URL
+const singleResult = await generatePortableHTML('./index.html', {
+  minifyHtml: true
+});
+
+// Recursively bundle a site
+const recursiveResult = await generateRecursivePortableHTML('https://example.com', 2, {
+  minifyCss: true
+});
+
+// Create multi-page bundle
+const multiPageBundle = await bundleMultiPageHTML([
+  { path: '/', html: '<html>...</html>' },
+  { path: '/about', html: '<html>...</html>' }
+]);
 ```
 
-## Documentation Architecture
+## Configuration
+
+See our full [Configuration Guide](https://manicinc.github.io/portapack/configuration) for detailed options.
 
-### Automatic Documentation Generation
+## CLI Options
 
-PortaPack uses a custom sidebar generator (`buildDocsSidebar()`) to:
-- Automatically scan TypeDoc-generated markdown files
-- Create dynamic, organized documentation sidebars
-- Support multiple documentation types (modules, classes, interfaces, etc.)
+PortaPack offers many command-line options for customizing the bundling process:
 
-#### How It Works
+```bash
+# Get full help
+portapack --help
+```
 
-1. TypeDoc generates markdown from source code comments
-2. Custom sidebar generator reads generated files
-3. VitePress renders dynamically generated sidebar
+For details, see the [CLI Reference](https://manicinc.github.io/portapack/cli).
 
 ## Next Steps
 
-- 📖 [Explore CLI Options](/cli)
-- 🛠 [Advanced Configuration](/configuration)
-- 💻 [API Reference](/api/README)
+- 📖 [Explore CLI Options](https://manicinc.github.io/portapack/cli)
+- 🛠 [Advanced Configuration](https://manicinc.github.io/portapack/configuration)
+- 💻 [API Reference](https://manicinc.github.io/portapack/api/)
 
 ## Troubleshooting
 
-Encountering issues? Check our [Troubleshooting Guide](/troubleshooting)
+Encountering issues? Check our [Troubleshooting Guide](https://manicinc.github.io/portapack/troubleshooting)
 
 ## Contributing
 
-Interested in improving PortaPack? 
-- [View Contributing Guidelines](/contributing)
-- [Development Guide](/development)
+Interested in improving PortaPack?
+- [View Contributing Guidelines](https://manicinc.github.io/portapack/contributing)
 
 ## Support