portapack 0.3.0 → 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

@@ -16,43 +16,32 @@ npm install -g portapack
 
 ## Command Syntax
 
-PortaPack supports two command styles for specifying input:
+The basic syntax for the PortaPack CLI is:
 
 ```bash
-# Positional argument style (recommended)
-portapack <path_or_url> [options]
-
-# Named argument style
-portapack --input <path_or_url> [options]
-# or using shorthand
-portapack -i <path_or_url> [options]
+portapack [input] [options]
 ```
 
-Both methods work identically - choose whichever you prefer.
+Where `[input]` is the path to a local HTML file or a remote URL.
 
 ## Options
 
 | Option | Shorthand | Description | Default |
 |--------|-----------|-------------|---------|
-| `<path_or_url>` or `--input <path_or_url>` | `-i` | Required. Input local file path or remote URL (http/https) to process. | - |
-| `--output <file>` | `-o` | Output file path for the bundled HTML. | `{input}.packed.html` |
+| `[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` |
-| `--recursive [depth]` | `-r` | Recursively bundle links up to depth. If depth omitted, defaults to 1. Only applies to remote URLs. | - (disabled) |
-| `--max-depth <n>` | | Set maximum depth for recursive crawling (alternative to `-r <n>`). | - |
-| `--base-url <url>` | `-b` | Base URL for resolving relative URLs found in the input HTML. | Input path/URL |
 | `--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` |
-| `--timeout <ms>` | `-t` | Network timeout in milliseconds for fetching remote resources. | `30000` (30 seconds) |
-| `--user-agent <string>` | `-U` | Custom User-Agent string for network requests. | Default Node.js agent |
-| `--include <glob>` | | Glob pattern for URLs to include during recursion (can be specified multiple times). | `**` (all) |
-| `--exclude <glob>` | | Glob pattern for URLs to exclude during recursion (can be specified multiple times). | - |
-| `--log-level <level>` | `-l` | Set logging level (debug, info, warn, error, silent). | `info` |
+| `--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` |
-| `--config <path>` | `-c` | Path to a configuration file (e.g., `.portapackrc.json`) to load options from. | - |
 | `--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. | - |
@@ -64,21 +53,13 @@ Both methods work identically - choose whichever you prefer.
 Bundle `index.html` into `bundle.html`:
 
 ```bash
-# Using positional argument style
 portapack ./index.html -o bundle.html
-
-# Using named argument style
-portapack -i ./index.html -o bundle.html
 ```
 
-Use default output name (`index.html.packed.html`):
+Use default output name (`index.packed.html`):
 
 ```bash
-# Using positional argument style
 portapack ./index.html
-
-# Using named argument style
-portapack -i ./index.html
 ```
 
 ### Web Page Bundling
@@ -86,11 +67,7 @@ portapack -i ./index.html
 Bundle a single remote webpage:
 
 ```bash
-# Using positional argument style
 portapack https://example.com -o example-bundle.html
-
-# Using named argument style
-portapack -i https://example.com -o example-bundle.html
 ```
 
 ### Recursive Bundling
@@ -113,15 +90,6 @@ Alternative using `--max-depth` option:
 portapack https://example.com --max-depth 2 -o site-bundle-depth2.html
 ```
 
-Recursively bundle only blog posts, excluding images:
-
-```bash
-portapack https://example.com -r \
-  --include "/blog/**" \
-  --exclude "**/*.{jpg,png,gif}" \
-  -o blog-bundle.html
-```
-
 ### Asset Handling
 
 Bundle without embedding assets (keep external links):
@@ -160,14 +128,6 @@ portapack ./index.html --no-minify-html -o selective-min.html
 portapack ./index.html --no-minify-js -o no-js-min.html
 ```
 
-### Advanced Network Options
-
-Bundle a remote page with a longer timeout and custom user agent:
-
-```bash
-portapack https://example.com -t 60000 -U "MyCustomBot/1.0" -o example-custom.html
-```
-
 ### Base URL for Relative Links
 
 Process a local file as if it were hosted at https://example.com:
@@ -198,14 +158,6 @@ See what files and assets would be processed without saving:
 portapack ./index.html --dry-run
 ```
 
-### Using a Configuration File
-
-Load options from a config file:
-
-```bash
-portapack -c ./.portapackrc.json
-```
-
 ### NPX Usage
 
 Use PortaPack without installing globally:
@@ -219,15 +171,10 @@ npx portapack ./index.html -o bundle.html
 | Code | Description |
 |------|-------------|
 | 0 | Success |
-| 1 | General Error (e.g., invalid options, file IO) |
-| 2 | Input Error (e.g., missing input, invalid URL) |
-| 3 | Network Error (e.g., fetch failed, timeout) |
-| 4 | Processing Error (e.g., parsing failed) |
-
-(Note: Specific error codes might vary)
+| 1 | Error |
 
 ## Related Resources
 
-- Getting Started (Link needs validation)
-- API Reference (Link needs validation)
-- Configuration Guide (Link needs validation)
+- [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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portapack",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "📦 A tool to bundle and minify HTML and all its dependencies into a single portable file.",
   "main": "dist/index.js",
   "module": "dist/index.js",