Heldsway SDK Documentation

This project contains the source code and content for the Heldsway SDK documentation, built using VitePress.

Project Overview

The Heldsway SDK is a lightweight (~5 KB) affiliate tracking solution designed for any storefront (Shopify, WordPress, plain HTML, or SPAs like React/Vue). It provides:

• Cookie-based Attribution: 30-day tracking via ?ref= URL parameters.
• Conversion Tracking: Reporting orders, line items, and customer details.
• Discount Validation: Automatic application of affiliate-embedded discount codes.
• SPA Compatibility: Automatic route change tracking for modern web apps.
• Dormant Mode: Graceful failure to ensure site performance.

Technology Stack

• Framework: VitePress (Vue-powered static site generator)
• Language: TypeScript (for configuration)
• Content: Markdown
• Styling: Vanilla CSS (found in .vitepress/theme/style.css)

Building and Running

Ensure you have Node.js (v18 or higher) installed.

Development

Start the local development server with hot-reload:

npm run dev

Production Build

Generate optimized static HTML/CSS/JS files:

npm run build

The output will be generated in the .vitepress/dist directory.

Preview

Preview the production build locally:

npm run preview

Directory Structure

• .vitepress/: VitePress configuration, theme customization, and build output.
  • config.ts: Main site configuration (navigation, sidebar, SEO).
  • theme/: Custom theme setup and global styles.
  • guide/: The core documentation content in Markdown format.
    • account-setup.md: Initial configuration instructions.
    • installation.md: How to add the SDK to a website.
    • track-order.md: Detailed guide on order tracking.
    • track-product-view.md, track-add-to-cart.md, etc.: E-commerce event tracking.
    • ...and other feature-specific guides.
• public/: Static assets (logos, icons, images) served at the root path.
• index.md: The home page configuration and hero section.

Development Conventions

• Content Updates: To add or edit documentation, modify the .md files in the guide/ directory.
• Navigation Changes: If you add a new page, remember to update the sidebar or navigation menu in .vitepress/config.ts.
• Assets: Use the /public folder for images and reference them using absolute paths (e.g., /logo.svg).
• Clean URLs: The project is configured for clean URLs (no .html extension). Ensure your deployment target supports this (usually by serving the .html file for a route).
• SEO: Meta tags and structured data (JSON-LD) are managed in .vitepress/config.ts.