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

Download the pipeline files

Make scripts executable:

chmod +x mdbook-logo-setup.sh batch-setup-example.sh

Set up a single project:

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

Clone or download this repository:

git clone <repository-url>
cd mdbook-logo-pipeline

Make scripts executable:
```
chmod +x *.sh
```
Verify prerequisites:
- mdbook installed
- Bash shell (Linux/macOS/WSL)
- Logo files in supported formats (PNG, JPG, JPEG, GIF, SVG, WebP)

Usage

Single Project Setup

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

Edit batch-setup-example.sh to configure your projects:

# 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:

# Shared logo for all projects
SHARED_LOGO="/path/to/shared/company-logo.png"
PROJECTS=(
    "/path/to/project1"
    "/path/to/project2"
    "/path/to/project3"
)

Run the batch processor:
```
./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

Validates environment variables and file paths
Checks mdbook project structure
Creates theme/ directory if needed
Copies logo file to project's theme directory
Processes CSS template, substituting placeholders
Updates book.toml with configuration
Creates timestamped backups of existing files
Verifies setup completion

Customization

Creating Custom CSS Templates

Copy and modify templates/mdbook-logo.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:

# 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:

# 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

"Logo file does not exist"
- Verify the LOGO_PATH points to an existing file
- Check file permissions (must be readable)
"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
"CSS template file does not exist"
- Check the CSS_TEMPLATE_PATH is correct
- Ensure template files are in the expected location
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

Run with help flag:

./mdbook-logo-setup.sh --help
./batch-setup-example.sh --help

Check script output: Scripts provide detailed logging with color-coded messages
Verify file structure: Ensure all required files are present and accessible

Examples

Corporate Documentation Setup

# 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

# 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

README.md

mdbook Logo Pipeline

Features