preparing to consolidate. yay microservices :)

2025-07-14 11:58:08 -05:00
parent 929348edff
commit 1f32c29d4a
7 changed files with 756 additions and 3 deletions
--- a/MdBook/GenerateMdBook.sh
+++ b/MdBook/GenerateMdBook.sh
@ -1,3 +0,0 @@
-#!/bin/bash
-
-mdbook build
--- a/mdbook/LLMLog.pdf
+++ b/mdbook/LLMLog.pdf
--- a/mdbook/README.md
+++ b/mdbook/README.md
@ -0,0 +1,288 @@
+# mdbook Logo Pipeline
+
+A robust shell script pipeline for adding company logos to [mdbook](https://rust-lang.github.io/mdBook/) projects with template-based customization and batch processing capabilities.
+
+## Features
+
+- **Template-based approach**: Separate code from data using external CSS and configuration templates
+- **Batch processing**: Set up logos across multiple mdbook projects efficiently
+- **Robust error handling**: Comprehensive validation, backup creation, and error recovery
+- **Responsive design**: Mobile-friendly logo placement with dark theme support
+- **Accessibility**: High contrast mode, reduced motion preferences, and RTL language support
+- **Safe operations**: Automatic backups of existing files before modification
+- **Flexible configuration**: Support for different logos per project or shared logos
+
+## Quick Start
+
+1. **Download the pipeline files**
+2. **Make scripts executable:**
+   ```bash
+   chmod +x mdbook-logo-setup.sh batch-setup-example.sh
+   ```
+3. **Set up a single project:**
+   ```bash
+   cd /path/to/your/mdbook/project
+   LOGO_PATH=/path/to/logo.png \
+   CSS_TEMPLATE_PATH=./templates/mdbook-logo.css \
+   ./mdbook-logo-setup.sh
+   ```
+
+## Directory Structure
+
+```
+mdbook-logo-pipeline/
+├── README.md                      # This file
+├── mdbook-logo-setup.sh          # Main setup script
+├── batch-setup-example.sh        # Multi-project batch processor
+├── templates/
+│   ├── mdbook-logo.css           # CSS template with logo styling
+│   └── book-config-addition.toml # mdbook configuration template
+└── examples/
+    └── logos/                    # Example logo files
+```
+
+## Installation
+
+1. **Clone or download this repository:**
+   ```bash
+   git clone <repository-url>
+   cd mdbook-logo-pipeline
+   ```
+
+2. **Make scripts executable:**
+   ```bash
+   chmod +x *.sh
+   ```
+
+3. **Verify prerequisites:**
+   - [mdbook](https://rust-lang.github.io/mdBook/guide/installation.html) installed
+   - Bash shell (Linux/macOS/WSL)
+   - Logo files in supported formats (PNG, JPG, JPEG, GIF, SVG, WebP)
+
+## Usage
+
+### Single Project Setup
+
+```bash
+cd /path/to/your/mdbook/project
+
+# Basic usage with CSS template
+LOGO_PATH=/path/to/logo.png \
+CSS_TEMPLATE_PATH=./templates/mdbook-logo.css \
+./mdbook-logo-setup.sh
+
+# With book configuration template
+LOGO_PATH=/path/to/logo.png \
+CSS_TEMPLATE_PATH=./templates/mdbook-logo.css \
+BOOK_CONFIG_TEMPLATE_PATH=./templates/book-config-addition.toml \
+./mdbook-logo-setup.sh
+```
+
+### Batch Processing Multiple Projects
+
+1. **Edit `batch-setup-example.sh`** to configure your projects:
+   ```bash
+   # Individual logos per project
+   PROJECTS=(
+       "/path/to/project1:/path/to/logos/company1-logo.png"
+       "/path/to/project2:/path/to/logos/company2-logo.svg"
+       "/path/to/project3:/path/to/logos/company3-logo.png"
+   )
+   ```
+
+   Or use a shared logo:
+   ```bash
+   # Shared logo for all projects
+   SHARED_LOGO="/path/to/shared/company-logo.png"
+   PROJECTS=(
+       "/path/to/project1"
+       "/path/to/project2"
+       "/path/to/project3"
+   )
+   ```
+
+2. **Run the batch processor:**
+   ```bash
+   ./batch-setup-example.sh
+   ```
+
+## Environment Variables
+
+### Required
+- `LOGO_PATH`: Full path to the logo file
+- `CSS_TEMPLATE_PATH`: Full path to the CSS template file
+
+### Optional
+- `BOOK_CONFIG_TEMPLATE_PATH`: Full path to book.toml template (falls back to inline config)
+
+## Template System
+
+### CSS Template (`templates/mdbook-logo.css`)
+
+The CSS template uses placeholders that are automatically replaced:
+- `LOGO_FILENAME`: Replaced with the actual logo filename
+
+**Key features:**
+- Responsive design (mobile, tablet, desktop)
+- Dark theme compatibility (coal, navy, ayu themes)
+- Accessibility support (high contrast, reduced motion)
+- RTL language support
+- Print CSS (hides logo when printing)
+- Optional animations and hover effects (commented out)
+
+### Book Configuration Template (`templates/book-config-addition.toml`)
+
+Contains mdbook configuration options including:
+- Custom CSS inclusion
+- Optional theme settings
+- Search configuration examples
+- Git repository integration
+- Additional customization options
+
+## What the Script Does
+
+1. **Validates** environment variables and file paths
+2. **Checks** mdbook project structure
+3. **Creates** `theme/` directory if needed
+4. **Copies** logo file to project's theme directory
+5. **Processes** CSS template, substituting placeholders
+6. **Updates** `book.toml` with configuration
+7. **Creates** timestamped backups of existing files
+8. **Verifies** setup completion
+
+## Customization
+
+### Creating Custom CSS Templates
+
+Copy and modify `templates/mdbook-logo.css`:
+
+```css
+/* Your custom CSS */
+.menu-title::before {
+    content: "";
+    background: url('LOGO_FILENAME') no-repeat center;
+    /* Your custom styling */
+}
+```
+
+The `LOGO_FILENAME` placeholder will be automatically replaced.
+
+### Logo Positioning Options
+
+The default template places logos:
+- Before the menu title (always visible)
+- Optionally before chapter titles (commented out)
+
+Uncomment sections in the CSS template to enable additional logo placements.
+
+### Theme Compatibility
+
+The CSS template includes optimizations for all mdbook themes:
+- **Light theme**: Default brightness
+- **Coal/Navy themes**: Slight brightness reduction
+- **Ayu theme**: Enhanced contrast for visibility
+
+## Advanced Usage
+
+### Multiple CSS Templates
+
+Create different templates for different project types:
+
+```bash
+# Corporate template
+CSS_TEMPLATE_PATH=./templates/corporate-logo.css
+
+# Open source template  
+CSS_TEMPLATE_PATH=./templates/oss-logo.css
+
+# Minimal template
+CSS_TEMPLATE_PATH=./templates/minimal-logo.css
+```
+
+### Custom Project Configurations
+
+Use different book configuration templates:
+
+```bash
+# API documentation projects
+BOOK_CONFIG_TEMPLATE_PATH=./templates/api-docs-config.toml
+
+# User guides
+BOOK_CONFIG_TEMPLATE_PATH=./templates/user-guide-config.toml
+```
+
+## Error Handling
+
+The scripts include comprehensive error handling:
+
+- **Validation**: Checks all file paths and permissions before processing
+- **Backups**: Creates timestamped backups of existing files
+- **Rollback**: Manual rollback using backup files if needed
+- **Cleanup**: Proper cleanup on script interruption
+- **Reporting**: Detailed success/failure reporting for batch operations
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Logo file does not exist"**
+   - Verify the `LOGO_PATH` points to an existing file
+   - Check file permissions (must be readable)
+
+2. **"Not in a valid mdbook project directory"**
+   - Ensure you're in a directory containing `book.toml`
+   - Run `mdbook init` to create a new project if needed
+
+3. **"CSS template file does not exist"**
+   - Check the `CSS_TEMPLATE_PATH` is correct
+   - Ensure template files are in the expected location
+
+4. **Logo not appearing**
+   - Run `mdbook build` and check the output
+   - Verify logo file was copied to `theme/` directory
+   - Check browser developer tools for CSS issues
+
+### Getting Help
+
+1. **Run with help flag:**
+   ```bash
+   ./mdbook-logo-setup.sh --help
+   ./batch-setup-example.sh --help
+   ```
+
+2. **Check script output:** Scripts provide detailed logging with color-coded messages
+
+3. **Verify file structure:** Ensure all required files are present and accessible
+
+## Examples
+
+### Corporate Documentation Setup
+
+```bash
+# Set up 20 different project documentation with individual company logos
+for i in {1..20}; do
+    cd "/path/to/docs/company${i}"
+    LOGO_PATH="/assets/logos/company${i}-logo.png" \
+    CSS_TEMPLATE_PATH="/shared/templates/corporate-mdbook.css" \
+    BOOK_CONFIG_TEMPLATE_PATH="/shared/templates/corporate-config.toml" \
+    /shared/scripts/mdbook-logo-setup.sh
+done
+```
+
+### Open Source Project Setup
+
+```bash
+# Single logo across multiple project repositories
+SHARED_LOGO="/assets/oss-project-logo.svg"
+for project in /repos/*/docs; do
+    cd "$project"
+    LOGO_PATH="$SHARED_LOGO" \
+    CSS_TEMPLATE_PATH="/templates/oss-mdbook.css" \
+    /scripts/mdbook-logo-setup.sh
+done
+```
+
+## Benefits
+
+- **Maintainable**: Update CSS template once, apply everywhere
+- **Flexible*
--- a/mdbook/batch-setup-example.sh
+++ b/mdbook/batch-setup-example.sh
@ -0,0 +1,252 @@
+#!/bin/bash
+set -euo pipefail
+
+# Example script for setting up mdbook logos across multiple projects
+# This demonstrates how to use the mdbook-logo-setup.sh script with templates
+
+# Configuration
+readonly SETUP_SCRIPT="./mdbook-logo-setup.sh"
+readonly CSS_TEMPLATE="./templates/mdbook-logo.css"
+readonly BOOK_CONFIG_TEMPLATE="./templates/book-config-addition.toml"
+
+# Color codes
+readonly GREEN='\033[0;32m'
+readonly BLUE='\033[0;34m'
+readonly RED='\033[0;31m'
+readonly NC='\033[0m'
+
+# Project configurations
+# Format: "project_path:logo_path"
+PROJECTS=(
+    "/path/to/project1:/path/to/logos/company1-logo.png"
+    "/path/to/project2:/path/to/logos/company2-logo.svg"
+    "/path/to/project3:/path/to/logos/company3-logo.png"
+    "/path/to/project4:/path/to/logos/company4-logo.jpg"
+    "/path/to/project5:/path/to/logos/company5-logo.png"
+    # Add your remaining 15 projects here...
+    # "/path/to/project6:/path/to/logos/company6-logo.png"
+    # "/path/to/project7:/path/to/logos/company7-logo.svg"
+    # ... etc
+)
+
+# Alternative: All projects use the same logo
+# SHARED_LOGO="/path/to/shared/company-logo.png"
+# PROJECTS=(
+#     "/path/to/project1"
+#     "/path/to/project2"
+#     "/path/to/project3"
+#     # ... etc
+# )
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $*"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*"
+}
+
+# Validate prerequisites
+validate_setup() {
+    log_info "Validating setup..."
+    
+    if [[ ! -f "$SETUP_SCRIPT" ]]; then
+        log_error "Setup script not found: $SETUP_SCRIPT"
+        exit 1
+    fi
+    
+    if [[ ! -x "$SETUP_SCRIPT" ]]; then
+        log_error "Setup script is not executable: $SETUP_SCRIPT"
+        log_info "Run: chmod +x $SETUP_SCRIPT"
+        exit 1
+    fi
+    
+    if [[ ! -f "$CSS_TEMPLATE" ]]; then
+        log_error "CSS template not found: $CSS_TEMPLATE"
+        exit 1
+    fi
+    
+    if [[ ! -f "$BOOK_CONFIG_TEMPLATE" ]]; then
+        log_error "Book config template not found: $BOOK_CONFIG_TEMPLATE"
+        exit 1
+    fi
+    
+    log_success "All prerequisites validated"
+}
+
+# Process a single project
+setup_project() {
+    local project_path="$1"
+    local logo_path="$2"
+    local project_name=$(basename "$project_path")
+    
+    log_info "Setting up project: $project_name"
+    log_info "Project path: $project_path"
+    log_info "Logo path: $logo_path"
+    
+    # Validate project directory
+    if [[ ! -d "$project_path" ]]; then
+        log_error "Project directory does not exist: $project_path"
+        return 1
+    fi
+    
+    # Validate logo file
+    if [[ ! -f "$logo_path" ]]; then
+        log_error "Logo file does not exist: $logo_path"
+        return 1
+    fi
+    
+    # Change to project directory
+    local original_dir=$(pwd)
+    cd "$project_path" || {
+        log_error "Failed to change to project directory: $project_path"
+        return 1
+    }
+    
+    # Run the setup script
+    if LOGO_PATH="$logo_path" \
+       CSS_TEMPLATE_PATH="$CSS_TEMPLATE" \
+       BOOK_CONFIG_TEMPLATE_PATH="$BOOK_CONFIG_TEMPLATE" \
+       "$original_dir/$SETUP_SCRIPT"; then
+        log_success "Successfully set up $project_name"
+    else
+        log_error "Failed to set up $project_name"
+        cd "$original_dir"
+        return 1
+    fi
+    
+    # Return to original directory
+    cd "$original_dir"
+    return 0
+}
+
+# Main execution
+main() {
+    local success_count=0
+    local failure_count=0
+    local failed_projects=()
+    
+    echo "mdbook Logo Batch Setup"
+    echo "======================="
+    echo ""
+    
+    validate_setup
+    
+    log_info "Processing ${#PROJECTS[@]} projects..."
+    echo ""
+    
+    for project_config in "${PROJECTS[@]}"; do
+        # Parse project configuration
+        if [[ "$project_config" == *":"* ]]; then
+            # Format: "project_path:logo_path"
+            local project_path="${project_config%:*}"
+            local logo_path="${project_config#*:}"
+        else
+            # Format: "project_path" (using shared logo)
+            local project_path="$project_config"
+            local logo_path="${SHARED_LOGO:-}"
+            
+            if [[ -z "$logo_path" ]]; then
+                log_error "No logo specified for $project_path and SHARED_LOGO not set"
+                ((failure_count++))
+                failed_projects+=("$project_path")
+                continue
+            fi
+        fi
+        
+        echo "----------------------------------------"
+        if setup_project "$project_path" "$logo_path"; then
+            ((success_count++))
+        else
+            ((failure_count++))
+            failed_projects+=("$(basename "$project_path")")
+        fi
+        echo ""
+    done
+    
+    # Print summary
+    echo "========================================"
+    echo "Batch Setup Complete!"
+    echo "========================================"
+    echo ""
+    echo "Results:"
+    echo "  Successful: $success_count"
+    echo "  Failed: $failure_count"
+    echo "  Total: ${#PROJECTS[@]}"
+    echo ""
+    
+    if [[ $failure_count -gt 0 ]]; then
+        echo "Failed projects:"
+        for project in "${failed_projects[@]}"; do
+            echo "  - $project"
+        done
+        echo ""
+    fi
+    
+    if [[ $success_count -gt 0 ]]; then
+        log_success "Setup completed for $success_count projects"
+        echo ""
+        echo "Next steps:"
+        echo "1. Test each project by running 'mdbook build' in project directories"
+        echo "2. Adjust templates if needed and re-run this script"
+        echo "3. Commit your changes to version control"
+    fi
+    
+    if [[ $failure_count -gt 0 ]]; then
+        exit 1
+    fi
+}
+
+# Show usage information
+usage() {
+    cat << EOF
+Usage: $0
+
+This script sets up mdbook logos across multiple projects using template files.
+
+Prerequisites:
+1. mdbook-logo-setup.sh script (executable)
+2. CSS template file: $CSS_TEMPLATE
+3. Book config template file: $BOOK_CONFIG_TEMPLATE
+
+Configuration:
+Edit the PROJECTS array in this script to specify your projects and logos.
+
+Two formats are supported:
+1. Individual logos: "project_path:logo_path"
+2. Shared logo: Set SHARED_LOGO variable and list only project paths
+
+Examples:
+  # Individual logos per project
+  PROJECTS=(
+    "/home/user/docs/project1:/assets/logo1.png"
+    "/home/user/docs/project2:/assets/logo2.svg"
+  )
+  
+  # Shared logo for all projects
+  SHARED_LOGO="/assets/company-logo.png"
+  PROJECTS=(
+    "/home/user/docs/project1"
+    "/home/user/docs/project2"
+  )
+
+The script will:
+- Validate all prerequisites
+- Process each project individually  
+- Provide detailed success/failure reporting
+- Continue processing even if some projects fail
+EOF
+}
+
+# Handle help flags
+if [[ "${1:-}" == "-h" ]] || [[ "${1:-}" == "--help" ]]; then
+    usage
+    exit 0
+fi
+
+# Run main function
+main "$@"
--- a/mdbook/book-config-addition.toml
+++ b/mdbook/book-config-addition.toml
@ -0,0 +1,72 @@
+# mdbook HTML output configuration with logo support
+# This section should be added to your book.toml file
+
+[output.html]
+# Custom CSS for logo and branding
+additional-css = ["theme/custom.css"]
+
+# Optional: Additional theme customizations
+# Uncomment and modify as needed
+
+# Set default theme (light, coal, navy, ayu, rust)
+# default-theme = "light"
+
+# Enable code copy button
+# copy-fonts = true
+
+# Git repository link (shows edit button)
+# git-repository-url = "https://github.com/yourorg/yourrepo"
+# git-repository-icon = "fa-github"
+
+# Custom favicon
+# site-url = "https://yoursite.com/"
+# favicon = "theme/favicon.ico"
+
+# Enable print support
+# print = { enable = true }
+
+# Search configuration
+# [output.html.search]
+# enable = true
+# limit-results = 30
+# teaser-word-count = 30
+# use-boolean-and = true
+# boost-title = 2
+# boost-hierarchy = 1
+# boost-paragraph = 1
+# expand = true
+# heading-split-level = 3
+
+# Playground configuration for code examples
+# [output.html.playground]
+# editable = false
+# copyable = true
+# copy-js = true
+# line-numbers = false
+# runnable = true
+
+# Optional: Custom head content
+# This is useful for analytics, fonts, or other custom HTML
+# [output.html]
+# additional-js = ["theme/custom.js"]
+# 
+# Or add to the <head> section:
+# head-template = """
+# <link rel="preconnect" href="https://fonts.googleapis.com">
+# <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+# <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+# """
+
+# Mathjax support for mathematical expressions
+# [output.html.playground]
+# line-numbers = true
+# [preprocessor.mathjax]
+
+# Custom 404 page
+# [output.html]
+# input-404 = "src/404.md"
+
+# Redirect configuration
+# [output.html.redirect]
+# "/old-page.html" = "/new-page.html"
+# "/legacy/" = "/current/"
--- a/mdbook/mdbook-logo-setup.sh
+++ b/mdbook/mdbook-logo-setup.sh
@ -0,0 +1,72 @@
+# mdbook HTML output configuration with logo support
+# This section should be added to your book.toml file
+
+[output.html]
+# Custom CSS for logo and branding
+additional-css = ["theme/custom.css"]
+
+# Optional: Additional theme customizations
+# Uncomment and modify as needed
+
+# Set default theme (light, coal, navy, ayu, rust)
+# default-theme = "light"
+
+# Enable code copy button
+# copy-fonts = true
+
+# Git repository link (shows edit button)
+# git-repository-url = "https://github.com/yourorg/yourrepo"
+# git-repository-icon = "fa-github"
+
+# Custom favicon
+# site-url = "https://yoursite.com/"
+# favicon = "theme/favicon.ico"
+
+# Enable print support
+# print = { enable = true }
+
+# Search configuration
+# [output.html.search]
+# enable = true
+# limit-results = 30
+# teaser-word-count = 30
+# use-boolean-and = true
+# boost-title = 2
+# boost-hierarchy = 1
+# boost-paragraph = 1
+# expand = true
+# heading-split-level = 3
+
+# Playground configuration for code examples
+# [output.html.playground]
+# editable = false
+# copyable = true
+# copy-js = true
+# line-numbers = false
+# runnable = true
+
+# Optional: Custom head content
+# This is useful for analytics, fonts, or other custom HTML
+# [output.html]
+# additional-js = ["theme/custom.js"]
+# 
+# Or add to the <head> section:
+# head-template = """
+# <link rel="preconnect" href="https://fonts.googleapis.com">
+# <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+# <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+# """
+
+# Mathjax support for mathematical expressions
+# [output.html.playground]
+# line-numbers = true
+# [preprocessor.mathjax]
+
+# Custom 404 page
+# [output.html]
+# input-404 = "src/404.md"
+
+# Redirect configuration
+# [output.html.redirect]
+# "/old-page.html" = "/new-page.html"
+# "/legacy/" = "/current/"
--- a/mdbook/mdbook-logo.css
+++ b/mdbook/mdbook-logo.css
@ -0,0 +1,72 @@
+# mdbook HTML output configuration with logo support
+# This section should be added to your book.toml file
+
+[output.html]
+# Custom CSS for logo and branding
+additional-css = ["theme/custom.css"]
+
+# Optional: Additional theme customizations
+# Uncomment and modify as needed
+
+# Set default theme (light, coal, navy, ayu, rust)
+# default-theme = "light"
+
+# Enable code copy button
+# copy-fonts = true
+
+# Git repository link (shows edit button)
+# git-repository-url = "https://github.com/yourorg/yourrepo"
+# git-repository-icon = "fa-github"
+
+# Custom favicon
+# site-url = "https://yoursite.com/"
+# favicon = "theme/favicon.ico"
+
+# Enable print support
+# print = { enable = true }
+
+# Search configuration
+# [output.html.search]
+# enable = true
+# limit-results = 30
+# teaser-word-count = 30
+# use-boolean-and = true
+# boost-title = 2
+# boost-hierarchy = 1
+# boost-paragraph = 1
+# expand = true
+# heading-split-level = 3
+
+# Playground configuration for code examples
+# [output.html.playground]
+# editable = false
+# copyable = true
+# copy-js = true
+# line-numbers = false
+# runnable = true
+
+# Optional: Custom head content
+# This is useful for analytics, fonts, or other custom HTML
+# [output.html]
+# additional-js = ["theme/custom.js"]
+# 
+# Or add to the <head> section:
+# head-template = """
+# <link rel="preconnect" href="https://fonts.googleapis.com">
+# <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+# <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+# """
+
+# Mathjax support for mathematical expressions
+# [output.html.playground]
+# line-numbers = true
+# [preprocessor.mathjax]
+
+# Custom 404 page
+# [output.html]
+# input-404 = "src/404.md"
+
+# Redirect configuration
+# [output.html.redirect]
+# "/old-page.html" = "/new-page.html"
+# "/legacy/" = "/current/"