🚀 HugDown Complete Guide #

Ultra-comprehensive documentation for the HugDown markdown transformation toolkit

📋 Overview #

HugDown is a comprehensive toolkit transforming markdown into multiple formats with professional theming, AI styling, and enterprise features.

Core Philosophy #

• DRY Principle: Single source markdown, multiple outputs
• AI-First Design: Intelligent theme selection
• Performance: Caching, async, parallel execution
• Accessibility: WCAG AA compliant
• Multi-Interface: CLI, API, programmatic

Project Structure #

hugdown/
├── beautysheet/    # FastAPI PDF converter with WebSocket
├── quicksheet/     # CLI converter with AI caching
├── hugmark/        # Hugo + PDF hybrid
└── hugo.md         # Hugo quick-start guide

🏗️ Architecture #

Component Matrix #

System Overview #

graph TB
    subgraph Input
        MD[📝 Markdown Files]
    end
    
    subgraph Processing
        BS[🎨 BeautySheet<br/>FastAPI Server]
        QS[⚡ QuickSheet<br/>Local CLI]
        HM[🌐 HugMark<br/>Hugo + PDF]
    end
    
    subgraph Output
        PDF1[📄 Server PDF]
        PDF2[📄 Local PDF]
        WEB[🌍 Static Site]
        PDF3[📄 Site PDFs]
    end
    
    MD --> BS --> PDF1
    MD --> QS --> PDF2
    MD --> HM --> WEB
    HM --> PDF3
    
    style BS fill:#e1f5ff
    style QS fill:#fff3e0
    style HM fill:#f3e5f5

Data Flow Architecture #

sequenceDiagram
    participant User
    participant Tool
    participant Converter
    participant AI
    participant Cache
    participant Output
    
    User->>Tool: Submit Markdown
    Tool->>Cache: Check Cache
    alt Cache Hit
        Cache-->>Tool: Return Cached
    else Cache Miss
        Tool->>AI: Analyze Content
        AI-->>Tool: Theme Recommendation
        Tool->>Converter: Process with Theme
        Converter->>Converter: MD→HTML→PDF
        Converter-->>Tool: Generated PDF
        Tool->>Cache: Store Result
    end
    Tool-->>Output: Deliver PDF
    Output-->>User: Download

🔧 BeautySheet #

Enterprise PDF generation service with real-time tracking

📊 Project State #

• Version: 0.1.0 (Alpha)
• Status: 🟡 Active Development
• Python: 3.8+ (tested on 3.10, 3.11)
• License: MIT
• Maturity: Early stage, core features working

🎯 Design Goals #

• Server-First: Built for multi-user server deployments
• Async Everything: Non-blocking job processing
• Real-Time: WebSocket progress tracking
• Scalable: Horizontal scaling with Redis/Database

Key Features #

🎨 AI-Powered Theming (30+ themes) 🔄 Async Processing (WebSocket updates) 💾 Smart Caching (Memory/File/SQLite) 🔒 Security (API key auth)

Technical Stack Deep Dive #

graph LR
    subgraph Frontend
        API[REST API]
        WS[WebSocket]
    end
    
    subgraph Core
        FA[FastAPI<br/>v0.95+]
        UV[Uvicorn<br/>ASGI Server]
        PY[Python<br/>3.8+]
    end
    
    subgraph Processing
        MD[Python-Markdown<br/>v3.4+]
        J2[Jinja2<br/>Templates]
        WP[WeasyPrint<br/>v65+]
    end
    
    subgraph Storage
        SQL[SQLAlchemy<br/>v2.0]
        RD[Redis<br/>v4.5]
        FS[File System]
    end
    
    API --> FA
    WS --> FA
    FA --> UV
    UV --> PY
    
    FA --> MD
    MD --> J2
    J2 --> WP
    
    FA --> SQL
    FA --> RD
    WP --> FS
    
    style FA fill:#00d084
    style WP fill:#ff6b6b

Architecture Layers #

graph TB
    subgraph API Layer
        REST[REST Endpoints]
        WSS[WebSocket Server]
        AUTH[Authentication]
    end
    
    subgraph Service Layer
        CONV[Conversion Service]
        THEME[Theme Manager]
        JOB[Job Manager]
        CACHE[Cache Manager]
    end
    
    subgraph Converter Layer
        MD2HTML[Markdown Parser]
        HTML2PDF[PDF Generator]
        PROC[HTML Processor]
    end
    
    subgraph Data Layer
        DB[(Database)]
        REDIS[(Redis Cache)]
        FILES[(File Storage)]
    end
    
    REST --> CONV
    WSS --> JOB
    AUTH --> REST
    
    CONV --> MD2HTML
    MD2HTML --> PROC
    PROC --> HTML2PDF
    
    CONV --> THEME
    CONV --> CACHE
    JOB --> CACHE
    
    CACHE --> REDIS
    CONV --> DB
    HTML2PDF --> FILES
    
    style CONV fill:#4a90e2
    style THEME fill:#f39c12
    style JOB fill:#e74c3c

Component Dependencies #

API Endpoints #

# Submit job
POST /api/conversion
{"content": "# Hello", "theme": "dracula"}

# Check status
GET /api/conversion/{job_id}

# WebSocket updates
WS /api/conversion/ws/{job_id}

# List themes
GET /api/themes

# Download PDF
GET /api/artifacts/{id}/download

Configuration #

API_HOST=0.0.0.0
API_PORT=8000
CACHE_DIR=./.cache
THEMES_DIR=./themes
API_KEY=your-key
WORKERS=4

Quick Start #

cd beautysheet
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn beautysheet.api.main:app --reload

Python Usage #

from beautysheet.converters import md_to_pdf

pdf = md_to_pdf(
    "# Document",
    "output.pdf",
    theme="corporate"
)

⚡ QuickSheet #

High-performance local converter with AI intelligence

📊 Project State #

• Version: 0.1.0 (Alpha)
• Status: 🟡 Active Development
• Python: 3.10+ (using modern features)
• License: MIT
• Maturity: Feature-rich, production-ready core

🎯 Design Goals #

• Local-First: Zero server dependencies
• AI-Powered: Intelligent theme selection
• Performance: Aggressive caching (1000x speedup)
• Developer-Friendly: Rich CLI with colors and progress

Key Features #

🧠 AI Content Analysis (type, tone, sentiment) ⚡ Multi-backend Caching (1000x faster) 🎨 30+ Themes + Interactive Explorer 📊 Telemetry & Performance Monitoring

Technical Stack Deep Dive #

graph LR
    subgraph CLI
        CLICK[Click<br/>v8.1+]
        RICH[Rich Console]
    end
    
    subgraph Core
        PY[Python<br/>3.10+]
        PYDANTIC[Pydantic<br/>v2.5+]
    end
    
    subgraph AI Engine
        OPENAI[OpenAI<br/>v1.12+]
        LANGCHAIN[LangChain<br/>v0.1+]
        NLP[Content Analyzer]
    end
    
    subgraph Conversion
        MD[Markdown<br/>v3.5+]
        J2[Jinja2<br/>v3.1+]
        WP[WeasyPrint<br/>v65+]
    end
    
    subgraph Styling
        NODE[Node.js<br/>16+]
        TW[Tailwind CSS<br/>v3.4]
        DAISY[daisyUI<br/>v4.12]
    end
    
    subgraph Cache
        MEM[Memory Cache]
        FILE[File Cache]
        SQLITE[SQLite Cache]
    end
    
    CLICK --> PY
    RICH --> CLICK
    
    PY --> OPENAI
    OPENAI --> LANGCHAIN
    LANGCHAIN --> NLP
    
    PY --> MD
    MD --> J2
    J2 --> WP
    
    NODE --> TW
    TW --> DAISY
    DAISY --> WP
    
    PY --> MEM
    PY --> FILE
    PY --> SQLITE
    
    style OPENAI fill:#10a37f
    style TW fill:#38bdf8
    style WP fill:#ff6b6b

AI Analysis Pipeline #

flowchart TD
    START[📝 Markdown Input] --> PARSE[Parse Content]
    PARSE --> TOKEN[Tokenization]
    
    TOKEN --> EXTRACT[Feature Extraction]
    EXTRACT --> TYPE[Document Type<br/>Detection]
    EXTRACT --> TONE[Emotional Tone<br/>Analysis]
    EXTRACT --> FORMAL[Formality<br/>Assessment]
    EXTRACT --> KEYWORDS[Keyword<br/>Extraction]
    
    TYPE --> CACHE_CHECK{Cache Hit?}
    TONE --> CACHE_CHECK
    FORMAL --> CACHE_CHECK
    KEYWORDS --> CACHE_CHECK
    
    CACHE_CHECK -->|Yes| CACHED[Return Cached<br/>Recommendation]
    CACHE_CHECK -->|No| SENTIMENT[Sentiment Analysis]
    
    SENTIMENT --> NEGATION[Negation Handling]
    NEGATION --> SCORING[Confidence Scoring]
    
    SCORING --> RECOMMEND[Theme<br/>Recommendation<br/>Engine]
    
    RECOMMEND --> PRIMARY[Primary Theme]
    RECOMMEND --> ALT1[Alternative 1]
    RECOMMEND --> ALT2[Alternative 2]
    
    PRIMARY --> STORE_CACHE[Store in Cache]
    ALT1 --> STORE_CACHE
    ALT2 --> STORE_CACHE
    
    STORE_CACHE --> OUTPUT[🎨 Theme Selection]
    CACHED --> OUTPUT
    
    style CACHE_CHECK fill:#ffd700
    style RECOMMEND fill:#4a90e2
    style OUTPUT fill:#00d084

Cache Architecture #

graph TB
    subgraph Application
        APP[QuickSheet CLI]
        ADAPTER[AI Cache Adapter]
    end
    
    subgraph Cache Layer
        CONFIG[Cache Config]
        MANAGER[Cache Manager]
    end
    
    subgraph Backends
        MEM[Memory Backend<br/>🔥 Fastest<br/>Session Only]
        FILE[File Backend<br/>⚡ Fast<br/>Persistent JSON]
        SQLITE[SQLite Backend<br/>💾 Robust<br/>Query Support]
    end
    
    subgraph Storage
        RAM[(RAM)]
        DISK[(Disk)]
        DB[(Database)]
    end
    
    APP --> ADAPTER
    ADAPTER --> CONFIG
    CONFIG --> MANAGER
    
    MANAGER --> MEM
    MANAGER --> FILE
    MANAGER --> SQLITE
    
    MEM --> RAM
    FILE --> DISK
    SQLITE --> DB
    
    style MEM fill:#ff6b6b
    style FILE fill:#ffd93d
    style SQLITE fill:#6bcf7f

Component Dependencies #

Performance Characteristics #

graph LR
    subgraph Without Cache
        OP1[Operation] --> TIME1[2-5s]
        TIME1 --> COST1[$$$]
    end
    
    subgraph With Cache
        OP2[Operation] --> CHECK{Cache?}
        CHECK -->|Hit| TIME2[1-5ms]
        CHECK -->|Miss| TIME3[2-5s]
        TIME2 --> COST2[$]
        TIME3 --> COST3[$$$]
        TIME3 --> STORE[Store]
        STORE --> TIME2
    end
    
    style TIME2 fill:#00d084
    style TIME1 fill:#ff6b6b

Essential Commands #

# Basic conversion
quicksheet md2pdf doc.md

# AI theme selection
quicksheet md2pdf doc.md --ai-theme

# Custom styling
quicksheet md2pdf doc.md \
  --theme=dracula \
  --page-size=letter \
  --landscape \
  --margin-preset=wide \
  --header-text="Header" \
  --pdf-a

# Theme explorer
quicksheet theme-preview --explore doc.md
quicksheet theme-preview --mood=creative
quicksheet theme-preview --doc-type=business

# Cache management
quicksheet cache stats
quicksheet cache clear
quicksheet warmup all

# Telemetry
quicksheet telemetry report
quicksheet telemetry visualize --metric=hit_rate

Cache Configuration #

export QUICKSHEET_CACHE_BACKEND=sqlite
export QUICKSHEET_CACHE_PATH=.cache/quicksheet
export QUICKSHEET_CACHE_TTL=604800

Or JSON config:

{
  "backend_type": "sqlite",
  "base_path": ".cache/quicksheet",
  "ttl": {
    "analysis": 604800,
    "theme": 2592000
  }
}

AI Theme Intelligence #

Content Analysis Pipeline:

Markdown → Tokenize → Extract Features → Sentiment Analysis
    ↓
Document Type + Tone + Formality + Context
    ↓
Theme Recommendation Engine
    ↓
Primary Theme + Alternatives

Theme Mapping:

Performance:

Setup #

cd quicksheet
python -m venv venv && source venv/bin/activate
pip install -e .
npm install && npm run css:prod
quicksheet info

🌐 HugMark #

Static site generator with PDF export

📊 Project State #

• Version: 1.0.0 (Stable)
• Status: 🟢 Production Ready
• Hugo: 0.128+ Extended
• Node.js: 16+
• License: ISC
• Maturity: Battle-tested, stable

🎯 Design Goals #

• Static-First: Pre-rendered HTML for speed
• Dual-Output: Website AND PDF from same source
• Modern UI: Tailwind CSS + daisyUI components
• Developer Joy: Hot reload, live preview

Key Features #

🌐 Hugo Static Sites (lightning fast) 🎨 daisyUI + Tailwind (modern UI) 📄 Puppeteer PDF Export (preserves styling) 🔧 Hot Reload Development

Technical Stack Deep Dive #

graph LR
    subgraph Static Site
        HUGO[Hugo<br/>v0.128+]
        GO[Go Templates]
        MD[Markdown]
    end
    
    subgraph Styling
        NODE[Node.js<br/>16+]
        TW[Tailwind CSS<br/>v3.4]
        DAISY[daisyUI<br/>v4.12]
        POST[PostCSS<br/>v8.5]
    end
    
    subgraph PDF Export
        EXPRESS[Express<br/>v5.1]
        PUPPET[Puppeteer<br/>v24.9]
        CHROME[Chromium]
    end
    
    subgraph Output
        HTML[Static HTML]
        CSS[Compiled CSS]
        PDF[PDF Files]
    end
    
    MD --> HUGO
    GO --> HUGO
    HUGO --> HTML
    
    NODE --> TW
    TW --> POST
    POST --> DAISY
    DAISY --> CSS
    
    CSS --> HTML
    HTML --> PUPPET
    EXPRESS --> PUPPET
    PUPPET --> CHROME
    CHROME --> PDF
    
    style HUGO fill:#ff4088
    style TW fill:#38bdf8
    style PUPPET fill:#00d084

Hugo Build Process #

flowchart TD
    START[📝 Content Files] --> FRONT[Parse Frontmatter]
    FRONT --> HUGO_PARSE[Hugo Parser]
    
    HUGO_PARSE --> TAXONOMY[Build Taxonomy]
    HUGO_PARSE --> PAGES[Generate Pages]
    HUGO_PARSE --> LISTS[Generate Lists]
    
    TAXONOMY --> TAGS[Tags]
    TAXONOMY --> CATS[Categories]
    
    PAGES --> LAYOUT[Apply Layouts]
    LISTS --> LAYOUT
    TAGS --> LAYOUT
    CATS --> LAYOUT
    
    LAYOUT --> PARTIALS[Include Partials]
    PARTIALS --> SHORTCODE[Process Shortcodes]
    
    SHORTCODE --> MINIFY[Minify HTML]
    MINIFY --> STATIC[Copy Static Assets]
    
    STATIC --> OUTPUT[📁 public/]
    
    style HUGO_PARSE fill:#ff4088
    style LAYOUT fill:#4a90e2
    style OUTPUT fill:#00d084

PDF Export Architecture #

sequenceDiagram
    participant Client
    participant Express
    participant Puppeteer
    participant Chrome
    participant FileSystem
    
    Client->>Express: POST /export-pdf
    Note over Client,Express: {url, options}
    
    Express->>Puppeteer: Launch Browser
    Puppeteer->>Chrome: Start Chromium
    Chrome-->>Puppeteer: Browser Instance
    
    Puppeteer->>Chrome: Navigate to URL
    Chrome->>Chrome: Load HTML + CSS
    Chrome->>Chrome: Execute JavaScript
    Chrome->>Chrome: Render Page
    
    Puppeteer->>Chrome: Generate PDF
    Chrome-->>Puppeteer: PDF Binary
    
    Puppeteer->>Express: PDF Data
    Express->>FileSystem: Save PDF (optional)
    Express-->>Client: Return PDF
    
    Puppeteer->>Chrome: Close Browser
    
    Note over Express,Chrome: Full DOM + CSS preserved

Development Workflow #

stateDiagram-v2
    [*] --> Edit: Developer
    
    Edit --> HugoWatch: Save Markdown
    Edit --> TailwindWatch: Save CSS
    
    HugoWatch --> HugoBuild: Detect Change
    TailwindWatch --> CSSBuild: Detect Change
    
    HugoBuild --> Reload: Generate HTML
    CSSBuild --> Reload: Compile CSS
    
    Reload --> Browser: Live Update
    Browser --> Edit: Continue
    
    Browser --> ExportPDF: Export Request
    ExportPDF --> PDFGen: Puppeteer
    PDFGen --> [*]: Download
    
    note right of HugoWatch
        ~100-200ms
        per build
    end note
    
    note right of CSSBuild
        ~500ms
        production build
    end note

Component Dependencies #

Hugo Content Structure #

graph TB
    ROOT[Hugo Root]
    
    ROOT --> CONTENT[content/]
    ROOT --> LAYOUTS[layouts/]
    ROOT --> STATIC[static/]
    ROOT --> ASSETS[assets/]
    ROOT --> THEMES[themes/]
    ROOT --> CONFIG[hugo.toml]
    
    CONTENT --> POSTS[posts/]
    CONTENT --> PAGES[pages/]
    CONTENT --> DOCS[docs/]
    
    POSTS --> POST1[first-post.md]
    POSTS --> POST2[second-post.md]
    
    LAYOUTS --> DEFAULT[_default/]
    LAYOUTS --> PARTIALS[partials/]
    LAYOUTS --> SHORT[shortcodes/]
    
    DEFAULT --> SINGLE[single.html]
    DEFAULT --> LIST[list.html]
    
    STATIC --> CSS_OUT[css/main.css]
    STATIC --> IMAGES[images/]
    STATIC --> JS[js/]
    
    ASSETS --> CSS_SRC[css/main.css]
    
    style CONTENT fill:#e3f2fd
    style LAYOUTS fill:#fff3e0
    style STATIC fill:#f3e5f5

Structure #

hugmark/
├── assets/css/main.css       # Tailwind source
├── content/                  # Markdown content
├── layouts/                  # Hugo templates
├── static/                   # Built assets
├── server.js                 # PDF export API
├── hugo.toml                 # Hugo config
└── tailwind.config.js        # Tailwind config

Usage #

# Development
npm install
npm run build:css
npm run dev

# Production
npm run build

# PDF export server
node server.js

# Export page
curl -X POST http://localhost:3000/export-pdf \
  -H "Content-Type: application/json" \
  -d '{"url": "http://localhost:1313/posts/my-post/"}' \
  --output output.pdf

Hugo Config #

baseURL = 'https://example.com/'
title = 'My Site'
theme = 'ananke'

[markup.goldmark.renderer]
  unsafe = true

Tailwind Config #

module.exports = {
  content: ["./content/**/*.md", "./layouts/**/*.html"],
  plugins: [require('daisyui')],
  daisyui: {
    themes: ["light", "dark", "dracula", "corporate"]
  }
}

🔀 Project Comparison #

Which Tool Should You Use? #

flowchart TD
    START{What do you need?}
    
    START -->|Server-based<br/>PDF service| SERVER{Multi-user?}
    START -->|Local PDF<br/>converter| LOCAL{Need AI?}
    START -->|Static website<br/>+ PDFs| STATIC
    
    SERVER -->|Yes| BS[✅ BeautySheet<br/>FastAPI Server<br/>WebSocket tracking]
    SERVER -->|No| LOCAL
    
    LOCAL -->|Yes| QS[✅ QuickSheet<br/>AI theme selection<br/>Advanced caching]
    LOCAL -->|No| QS2[✅ QuickSheet<br/>Fast & simple]
    
    STATIC --> HM[✅ HugMark<br/>Hugo + Puppeteer<br/>Dual output]
    
    style BS fill:#e1f5ff
    style QS fill:#fff3e0
    style QS2 fill:#fff3e0
    style HM fill:#f3e5f5

Feature Comparison Matrix #

Performance Comparison #

graph TB
    subgraph BeautySheet Server
        BS1[Request] --> BS2[Queue]
        BS2 --> BS3[Process]
        BS3 --> BS4[~2-3s]
        BS4 --> BS5[WebSocket<br/>Updates]
    end
    
    subgraph QuickSheet CLI
        QS1[Command] --> QS2{Cache?}
        QS2 -->|Hit| QS3[~1-5ms ⚡]
        QS2 -->|Miss| QS4[~2-5s]
    end
    
    subgraph HugMark Static
        HM1[hugo build] --> HM2[~200ms<br/>per 100 pages]
        HM2 --> HM3[Static HTML]
        HM3 --> HM4[PDF Export<br/>~1-2s per page]
    end
    
    style QS3 fill:#00d084
    style HM2 fill:#00d084

Use Case Decision Tree #

graph TD
    Q1{Need server<br/>API?}
    Q1 -->|Yes| BS[BeautySheet]
    Q1 -->|No| Q2{Building<br/>website?}
    
    Q2 -->|Yes| HM[HugMark]
    Q2 -->|No| Q3{Need AI<br/>themes?}
    
    Q3 -->|Yes| QS1[QuickSheet<br/>with --ai-theme]
    Q3 -->|No| Q4{Batch<br/>processing?}
    
    Q4 -->|Yes| QS2[QuickSheet<br/>+ shell script]
    Q4 -->|No| QS3[QuickSheet<br/>single files]
    
    BS --> USE1[API integration<br/>Multi-user service<br/>Job tracking]
    HM --> USE2[Documentation site<br/>Blog with PDFs<br/>Marketing pages]
    QS1 --> USE3[Smart documents<br/>Content analysis<br/>Auto-theming]
    QS2 --> USE4[Documentation batch<br/>Report generation<br/>CI/CD pipelines]
    QS3 --> USE5[Quick conversions<br/>One-off documents<br/>Local work]
    
    style BS fill:#e1f5ff
    style HM fill:#f3e5f5
    style QS1 fill:#fff3e0
    style QS2 fill:#fff3e0
    style QS3 fill:#fff3e0

Complexity vs Power #

quadrantChart
    title Tool Positioning
    x-axis Low Complexity --> High Complexity
    y-axis Basic Features --> Advanced Features
    quadrant-1 Power User
    quadrant-2 Enterprise
    quadrant-3 Getting Started
    quadrant-4 Professional
    
    QuickSheet (Simple): [0.3, 0.4]
    QuickSheet (AI): [0.5, 0.7]
    BeautySheet: [0.7, 0.8]
    HugMark: [0.6, 0.6]

🎯 Common Patterns #

Pattern 1: Local Conversion #

quicksheet md2pdf doc.md --theme=corporate

Pattern 2: Batch Processing #

for file in docs/*.md; do
  quicksheet md2pdf "$file" --theme=dracula
done

Pattern 3: API Processing #

import requests

response = requests.post(
    "http://localhost:8000/api/conversion",
    json={"content": md, "theme": "corporate"},
    headers={"X-API-Key": "key"}
)
job_id = response.json()["job_id"]

Pattern 4: CI/CD Integration #

# .github/workflows/docs.yml
jobs:
  generate:
    steps:
      - run: pip install quicksheet
      - run: quicksheet md2pdf docs/*.md --theme=corporate

🎨 Advanced Features #

Custom Theme #

/* themes/custom.css */
:root {
  --primary: #3b82f6;
  --base-100: #ffffff;
  --base-content: #1f2937;
}

quicksheet md2pdf doc.md --theme=custom

AI Analysis #

from quicksheet.ai.content_analyzer import ContentAnalyzer

analyzer = ContentAnalyzer()
analysis = analyzer.analyze(markdown)

print(analysis.document_type)
print(analysis.emotional_tone)
print(analysis.get_theme_recommendations())

Cache Decorator #

from quicksheet.core.cache.ai_adapter import cached_ai_operation

@cached_ai_operation(model="gpt-4", operation="analyze")
def custom_analysis(content):
    return ai_result

🔧 Configuration Reference #

BeautySheet Environment #

API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false
CACHE_DIR=./.cache
THEMES_DIR=./themes
PDF_OUTPUT_DIR=./output
API_KEY=your-api-key
WORKERS=4
CACHE_MAX_SIZE_GB=2.0
CACHE_RETENTION_DAYS=30

QuickSheet Environment #

QUICKSHEET_CACHE_BACKEND=sqlite
QUICKSHEET_CACHE_PATH=.cache/quicksheet
QUICKSHEET_CACHE_TTL=604800
QUICKSHEET_CACHE_MAX_SIZE=1000
QUICKSHEET_CACHE_CONFIG=cache.json

🚀 Best Practices #

Performance #

✅ Use caching for repeated operations ✅ Enable parallel processing for batches ✅ Pre-warm caches with warmup commands ✅ Use SQLite backend for high volume ✅ Monitor cache hit rates

Theme Selection #

✅ Use AI theme for unknown content ✅ Set project defaults in config ✅ Create custom themes for branding ✅ Test themes with preview before export

Security #

✅ Set strong API keys ✅ Use HTTPS in production ✅ Limit CORS origins ✅ Rotate keys regularly ✅ Monitor access logs

Content Organization #

✅ Use frontmatter for metadata ✅ Organize content in directories ✅ Use consistent naming conventions ✅ Version control markdown sources ✅ Separate content from configuration

🐛 Troubleshooting #

PDF Generation Fails #

Check WeasyPrint dependencies:

# Debian/Ubuntu
sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-0

# macOS
brew install pango cairo gdk-pixbuf

Cache Issues #

quicksheet cache clear
quicksheet cache clean
quicksheet cache config --show

Theme Not Found #

quicksheet theme list
quicksheet info

Puppeteer Errors #

# Install Chromium
npx puppeteer browsers install chrome

# Or specify executable
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

📊 Performance Metrics #

QuickSheet Cache Performance #

• Analysis: 2-5s → 1-5ms (1000x faster)
• Theme Selection: 3-7s → 1-5ms (1000x faster)
• Full Document: 5-10s → 0.5-1s (10x faster)

BeautySheet Throughput #

• Single Document: ~2-3s
• Concurrent Jobs: 4-8 parallel
• WebSocket Latency: <100ms

HugMark Build Speed #

• Hugo Build: ~100-200ms per 100 pages
• PDF Export: ~1-2s per page
• CSS Build: ~500ms (production)

🔗 Quick Reference #

Essential Commands #

# BeautySheet
uvicorn beautysheet.api.main:app --reload

# QuickSheet
quicksheet md2pdf doc.md --ai-theme
quicksheet cache stats
quicksheet theme-preview --explore doc.md

# HugMark
hugo server
npm run build
node server.js

File Locations #

/home/dev/hugdown/
├── beautysheet/        # API-based converter
├── quicksheet/         # CLI converter
├── hugmark/            # Hugo site
└── docs/               # Generated documentation

Documentation #

• BeautySheet: beautysheet/README.md
• QuickSheet: quicksheet/README.md
• HugMark: hugmark/package.json
• This Guide: /home/dev/docs/hugdown.md

🎓 Learning Path #

Beginner Path #

journey
    title Your HugDown Journey
    section Week 1
      Install QuickSheet: 5: You
      First PDF conversion: 4: You
      Try different themes: 5: You
    section Week 2
      Explore AI themes: 4: You
      Batch processing: 3: You
      Custom theme creation: 4: You
    section Week 3
      Set up BeautySheet API: 3: You
      WebSocket tracking: 4: You
      API integration: 4: You
    section Week 4
      Build Hugo site: 5: You
      Configure PDF export: 4: You
      Production deployment: 5: You

Quick Start Paths #

graph LR
    START[Choose Your Path]
    
    START --> PATH1[🚀 Fast Start<br/>5 minutes]
    START --> PATH2[💡 Smart Start<br/>15 minutes]
    START --> PATH3[🏢 Full Stack<br/>1 hour]
    
    PATH1 --> STEP1A[Install QuickSheet]
    STEP1A --> STEP1B[Run: quicksheet md2pdf doc.md]
    STEP1B --> DONE1[✅ Done!]
    
    PATH2 --> STEP2A[Install QuickSheet]
    STEP2A --> STEP2B[Set up AI API key]
    STEP2B --> STEP2C[Run: quicksheet md2pdf --ai-theme]
    STEP2C --> STEP2D[Explore themes]
    STEP2D --> DONE2[✅ Smart PDFs!]
    
    PATH3 --> STEP3A[Install BeautySheet]
    STEP3A --> STEP3B[Configure database]
    STEP3B --> STEP3C[Start API server]
    STEP3C --> STEP3D[Integrate with app]
    STEP3D --> DONE3[✅ Production Ready!]
    
    style PATH1 fill:#00d084
    style PATH2 fill:#ffd93d
    style PATH3 fill:#4a90e2

Skill Progression #

1️⃣ Beginner: QuickSheet CLI basics 2️⃣ Intermediate: AI themes + caching 3️⃣ Advanced: BeautySheet API setup 4️⃣ Expert: HugMark + custom themes 5️⃣ Master: CI/CD integration 6️⃣ Architect: Multi-tool workflows

🌐 Complete Ecosystem #

HugDown at a Glance #

mindmap
  root((HugDown<br/>Toolkit))
    BeautySheet
      FastAPI Server
      WebSocket Updates
      Async Jobs
      Multi-user
      API Integration
    QuickSheet
      Local CLI
      AI Themes
      Smart Caching
      Telemetry
      Developer Tools
    HugMark
      Hugo Static
      PDF Export
      Modern UI
      Hot Reload
      Dual Output
    Shared
      30+ Themes
      WeasyPrint
      Markdown
      Accessibility
      Performance

Tech Stack Overview #

graph TB
    subgraph Languages
        PY[Python 3.8+]
        JS[JavaScript ES6+]
        GO[Go Templates]
    end
    
    subgraph Frameworks
        FASTAPI[FastAPI]
        CLICK[Click CLI]
        HUGO[Hugo SSG]
        EXPRESS[Express]
    end
    
    subgraph Rendering
        WP[WeasyPrint]
        PUPPET[Puppeteer]
    end
    
    subgraph Styling
        TW[Tailwind CSS]
        DAISY[daisyUI]
        POST[PostCSS]
    end
    
    subgraph AI
        OPENAI[OpenAI]
        LANG[LangChain]
    end
    
    subgraph Storage
        SQLITE[SQLite]
        REDIS[Redis]
        FS[File System]
    end
    
    PY --> FASTAPI
    PY --> CLICK
    PY --> WP
    JS --> EXPRESS
    JS --> PUPPET
    GO --> HUGO
    
    FASTAPI --> REDIS
    CLICK --> SQLITE
    
    PY --> OPENAI
    OPENAI --> LANG
    
    JS --> TW
    TW --> DAISY
    DAISY --> POST
    
    WP --> FS
    PUPPET --> FS
    
    style PY fill:#3776ab
    style JS fill:#f7df1e
    style GO fill:#00add8

🎬 Real-World Examples #

Example 1: Developer Documentation #

flowchart LR
    DEV[Developer] --> WRITE[Write API Docs<br/>in Markdown]
    WRITE --> QS[QuickSheet<br/>--theme=nord]
    QS --> PDF1[PDF for Print]
    
    WRITE --> HM[HugMark<br/>Hugo Build]
    HM --> WEB[docs.company.com]
    HM --> PDF2[PDF Downloads]
    
    style QS fill:#fff3e0
    style HM fill:#f3e5f5

Commands:

# Quick PDF for review
quicksheet md2pdf api-docs.md --theme=nord --pdf-a

# Deploy documentation site
cd hugmark && hugo && npm run build

Example 2: Marketing Team #

flowchart TB
    TEAM[Marketing Team] --> WRITE[Create Brochures<br/>in Markdown]
    WRITE --> BS[BeautySheet API]
    
    BS --> JOB1[Job Queue]
    JOB1 --> PDF1[English PDF]
    JOB1 --> PDF2[Spanish PDF]
    JOB1 --> PDF3[French PDF]
    
    PDF1 --> TRACK[WebSocket<br/>Progress]
    PDF2 --> TRACK
    PDF3 --> TRACK
    
    TRACK --> DONE[Download All]
    
    style BS fill:#e1f5ff

API Call:

# Batch multilingual brochures
for lang in ['en', 'es', 'fr']:
    job = api.submit_conversion(
        content=load_template(lang),
        theme='luxury',
        options={'language': lang}
    )
    track_job(job.id)

Example 3: Academic Papers #

flowchart LR
    SCHOLAR[Researcher] --> WRITE[Write Paper<br/>in Markdown]
    WRITE --> AI[QuickSheet AI<br/>Analysis]
    
    AI --> DETECT[Detect: Academic<br/>Serious Tone]
    DETECT --> THEME[Recommend:<br/>corporate, nord]
    
    THEME --> CONVERT[Generate PDF]
    CONVERT --> REVIEW[Review Output]
    
    REVIEW -->|Adjust| WRITE
    REVIEW -->|Perfect| SUBMIT[Submit Paper]
    
    style AI fill:#fff3e0

Commands:

# AI-powered academic paper
quicksheet md2pdf research-paper.md \
  --ai-theme \
  --page-size=letter \
  --margin-preset=normal \
  --header-text="University of Science" \
  --footer-text="Page {page} of {total}" \
  --pdf-a

📝 Visual Cheat Sheet #

One-Command Quick Reference #

graph TB
    subgraph "🚀 QuickSheet - Local CLI"
        QS1["quicksheet md2pdf doc.md"]
        QS2["quicksheet md2pdf doc.md --ai-theme"]
        QS3["quicksheet theme-preview --explore doc.md"]
        QS4["quicksheet cache stats"]
    end
    
    subgraph "🔧 BeautySheet - API Server"
        BS1["uvicorn beautysheet.api.main:app --reload"]
        BS2["curl -X POST /api/conversion"]
        BS3["ws://localhost:8000/api/conversion/ws/{id}"]
    end
    
    subgraph "🌐 HugMark - Static Site"
        HM1["hugo server"]
        HM2["npm run build:css"]
        HM3["node server.js"]
        HM4["curl -X POST /export-pdf"]
    end
    
    style QS1 fill:#d4edda
    style BS1 fill:#d1ecf1
    style HM1 fill:#f8d7da

File Structure at a Glance #

/home/dev/hugdown/
│
├── 📁 beautysheet/          ← Server PDF API
│   ├── src/beautysheet/
│   │   ├── api/            ← FastAPI routes
│   │   ├── converters/     ← MD→PDF pipeline
│   │   ├── core/           ← Config & cache
│   │   └── cli/            ← CLI tools
│   ├── .env                ← Environment config
│   └── requirements.txt    ← Python deps
│
├── 📁 quicksheet/           ← Local CLI with AI
│   ├── src/quicksheet/
│   │   ├── cli/            ← Click commands
│   │   ├── core/           ← Converters
│   │   ├── ai/             ← AI analysis
│   │   └── assets/         ← Tailwind CSS
│   ├── pyproject.toml      ← Python project
│   └── package.json        ← Node/CSS deps
│
├── 📁 hugmark/              ← Hugo + PDF
│   ├── content/            ← Markdown files
│   ├── layouts/            ← Hugo templates
│   ├── static/             ← Built assets
│   ├── hugo.toml           ← Hugo config
│   ├── server.js           ← PDF export API
│   └── package.json        ← Node deps
│
└── 📄 hugo.md               ← Quick start guide

Command Decision Matrix #

🌟 Key Takeaways #

✨ Three Tools, One Goal: Transform markdown into professional outputs ✨ QuickSheet: Best for local work with AI intelligence ✨ BeautySheet: Perfect for server deployments and teams ✨ HugMark: Ideal for documentation sites with PDF exports ✨ 30+ Themes: Professional styling out of the box ✨ 1000x Faster: With intelligent caching ✨ AI-Powered: Automatic theme selection based on content ✨ Production Ready: Battle-tested core, active development

When in Doubt #

graph LR
    DOUBT{Not sure?}
    DOUBT -->|Start simple| QS[Try QuickSheet]
    QS --> LIKE{Like it?}
    LIKE -->|Yes| GROW[Grow from there]
    LIKE -->|No| TRY[Try another tool]
    
    style QS fill:#00d084

Start Command: quicksheet md2pdf README.md --ai-theme

📍 File Location: /home/dev/docs/hugdown.md 📅 Last Updated: 2025-11-07 🏷️ Project: HugDown Toolkit v1.0 👤 Created for: Beginners to Advanced Users