diff --git a/MdBook/GenerateMdBook.sh b/MdBook/GenerateMdBook.sh deleted file mode 100644 index e6c79b7..0000000 --- a/MdBook/GenerateMdBook.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/bash - -mdbook build \ No newline at end of file diff --git a/mdbook/LLMLog.pdf b/mdbook/LLMLog.pdf new file mode 100755 index 0000000..21c48c9 Binary files /dev/null and b/mdbook/LLMLog.pdf differ diff --git a/mdbook/README.md b/mdbook/README.md new file mode 100644 index 0000000..b93858d --- /dev/null +++ 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 + 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* \ No newline at end of file diff --git a/mdbook/batch-setup-example.sh b/mdbook/batch-setup-example.sh new file mode 100644 index 0000000..1428af6 --- /dev/null +++ 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 "$@" \ No newline at end of file diff --git a/mdbook/book-config-addition.toml b/mdbook/book-config-addition.toml new file mode 100644 index 0000000..41fe88c --- /dev/null +++ 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 section: +# head-template = """ +# +# +# +# """ + +# 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/" \ No newline at end of file diff --git a/mdbook/mdbook-logo-setup.sh b/mdbook/mdbook-logo-setup.sh new file mode 100644 index 0000000..41fe88c --- /dev/null +++ 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 section: +# head-template = """ +# +# +# +# """ + +# 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/" \ No newline at end of file diff --git a/mdbook/mdbook-logo.css b/mdbook/mdbook-logo.css new file mode 100644 index 0000000..41fe88c --- /dev/null +++ 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 section: +# head-template = """ +# +# +# +# """ + +# 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/" \ No newline at end of file