Getting Started

Minimal Setup

Installation:
- Ensure bookdown is installed via npm (npm install -g bookdown).
- Initialize a bookdown.json in your project root with the template:
```
{
  "template": "bookdown/themes"
}
```
- Run bookdown build to generate the book with default styles (cerulean for Bootswatch, ghcolors for Prism).
First Use Case:
- Quickly style a technical documentation site or ebook with minimal configuration. Example:
```
CSS_BOOTSWATCH=flatly CSS_PRISM=okaidia bookdown build
```

Where to Look First

bookdown.json: Core configuration file for theme and TOC settings.
Bootswatch/Prism Docs: bootswatch.com and prism-themes for visual previews.
Default Output: Inspect _book/ folder post-build to verify styling.

Implementation Patterns

Workflows

Theming Workflow:
- Design Phase: Test Bootswatch/Prism themes via environment variables before committing to bookdown.json.
- Iterative Builds: Use bookdown serve to preview changes locally with:
```
CSS_BOOTSWATCH=superhero bookdown serve
```
- Production Build: Set environment variables in CI/CD (e.g., GitHub Actions) or deployment scripts.
TOC Customization:
- Dynamically adjust collapsible levels for large documents:
```
"theme": {
  "toc": {
    "collapsibleFromLevel": 2  // Collapse sections from level 2+
  }
}
```
- Pair with bookdown’s built-in TOC plugins (e.g., bookdown-plugin-toc) for advanced features.
Syntax Highlighting:
- Extend Prism support by including custom languages in _book/assets/js/prism.js (e.g., for Laravel Blade templates):
```
Prism.languages.blade = Prism.languages.extend('markup', {
  // Custom Blade syntax rules
});
```

Integration Tips

Laravel Projects:
- Use the package to style API documentation or admin panels. Example:
```
# Build docs alongside Laravel assets
CSS_BOOTSWATCH=sandstone bookdown build && npm run dev
```
- Embed the generated HTML in Laravel views via Blade:
```
@include('bookdown.output.index')
```
Static Site Generators:
- Combine with tools like laravel-mix to bundle Bookdown assets with Laravel’s frontend stack.

Gotchas and Tips

Pitfalls

Environment Variable Overrides:
- Issue: Environment variables (CSS_BOOTSWATCH, CSS_PRISM) are not persisted in bookdown.json and must be set per-build.
- Fix: Document the required variables in your team’s deployment guide or use a .env file:
```
CSS_BOOTSWATCH=darkly
CSS_PRISM=twilight
```
Prism Language Support:
- Issue: Missing syntax highlighting for custom languages (e.g., Laravel Blade) requires manual Prism configuration.
- Fix: Extend prism.js as shown in the workflows section or use a community plugin like prism-laravel.
TOC Configuration Limits:
- Issue: collapsibleFromLevel only accepts integers; no support for dynamic or conditional logic.
- Workaround: Use JavaScript post-build to modify TOC behavior (e.g., via bookdown’s afterBuild hook).
Deprecated Package:
- Issue: The package is unmaintained (last release: 2018). Bootswatch/Prism themes may break with updates.
- Mitigation:
  - Fork the repo to patch compatibility issues.
  - Monitor Bookdown’s main repo for theme updates.

Debugging

Styling Issues:
- Inspect the _book/assets/css/ folder post-build to verify loaded styles. Conflicts may arise if other CSS files override Bootswatch.
- Use browser dev tools to check if environment variables are correctly applied (e.g., cerulean class on <body>).
Build Failures:
- Ensure bookdown.json is valid JSON (use JSONLint).
- Check Node.js/npm versions; older versions may lack support for bookdown’s template system.

Extension Points

Custom Themes:

Override default styles by extending Bootswatch’s SASS variables in a custom CSS file (e.g., _book/assets/css/custom.css):

@import "~bootswatch/cerulean/bootstrap.scss";
@import "~prismjs/themes/ghcolors.css";

/* Custom overrides */
body { font-family: 'Helvetica Neue', sans-serif; }

Dynamic Themes:

Use a Laravel middleware to set CSS_BOOTSWATCH based on user preferences (e.g., saved in the database):

// app/Http/Middleware/SetBookdownTheme.php
public function handle($request, Closure $next) {
    if ($request->user()->prefers_dark_mode) {
        putenv('CSS_BOOTSWATCH=darkly');
    }
    return $next($request);
}

Plugin Integration:

Extend functionality with bookdown plugins. Example: Add a plugin to auto-generate a theme selector:

// bookdown-plugin-theme-selector.js
module.exports = function(bookdown) {
  bookdown.on('afterBuild', () => {
    // Inject theme selector HTML/JS
  });
};

Themes Laravel Package