quarto-online-books

name	quarto-online-books
description	Comprehensive toolkit for creating, configuring, and publishing professional online books with Quarto. This skill should be used when users want to create digital books, technical documentation, academic textbooks, or multi-chapter reference guides with HTML output, interactive elements, and modern web features.

Quarto Online Books

Overview

This skill provides comprehensive guidance and tools for creating professional online books using Quarto, a scientific and technical publishing system that supports multiple output formats with a focus on web-first presentation.

Quick Start Workflow

To create a new online book quickly:

# Create book project
quarto create project book mybook
cd mybook

# Preview during development
quarto preview

# Build for publication
quarto render

# Deploy to GitHub Pages
quarto publish gh-pages

Core Book Creation Tasks

1. Initialize New Book Project

To create a new book from scratch:

quarto create project book <book-name>

Or use the provided initialization script for a more configured setup:

python scripts/init_book.py --name "My Book" --author "Author Name" --chapters 5

This creates the essential structure:

• _quarto.yml - Main configuration file
• index.qmd - Book introduction/preface
• Chapter files (chapter1.qmd, chapter2.qmd, etc.)
• .gitignore - Excludes _book/ output directory
• references.bib - Bibliography file (if academic option selected)

2. Configure Book Structure

Edit _quarto.yml to define book metadata and structure. Refer to references/quarto_yml_config.md for complete options.

Basic configuration:

project:
  type: book
  output-dir: _book

book:
  title: "Your Book Title"
  author: "Your Name"
  date: today
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd
    - chapter3.qmd

format:
  html:
    theme: cosmo
    toc: true
    number-sections: true

Advanced multi-part structure:

book:
  title: "Advanced Book"
  chapters:
    - index.qmd
    - part: "Part I: Foundations"
      chapters:
        - intro.qmd
        - basics.qmd
    - part: "Part II: Advanced Topics"
      chapters:
        - advanced.qmd
        - case-studies.qmd
  appendices:
    - appendix-a.qmd
    - references.qmd

3. Author Rich Content

Cross-References

Use proper label prefixes for referenceable elements:

## Introduction {#sec-intro}

See @fig-diagram for the system architecture.

![System Architecture](images/architecture.png){#fig-diagram}

As discussed in @sec-intro, the system uses...

| Column 1 | Column 2 |
|----------|----------|
| Data     | Value    |
: Important metrics {#tbl-metrics}

Reference @tbl-metrics for details.

Callout Blocks

Emphasize important content:

::: {.callout-note}
## Key Concept
This fundamental principle underlies all subsequent topics.
:::

::: {.callout-warning}
Avoid this common mistake when implementing...
:::

::: {.callout-tip}
## Pro Tip
Use this shortcut to save time.
:::

Computational Content

Include executable code with outputs:

```{python}
#| label: fig-plot
#| fig-cap: "Quarterly Revenue Growth"
#| code-fold: true

import matplotlib.pyplot as plt
quarters = ['Q1', 'Q2', 'Q3', 'Q4']
revenue = [100, 120, 140, 180]
plt.bar(quarters, revenue)
plt.ylabel('Revenue (M$)')
plt.show()
```

4. Add and Manage Chapters

To add new chapters programmatically:

python scripts/add_chapter.py --title "New Chapter" --after "chapter2.qmd"

This automatically:

• Creates the chapter file with proper frontmatter
• Updates _quarto.yml with correct placement
• Maintains numbering consistency

5. Apply Custom Styling

Use pre-built book themes from assets/custom-themes/:

# Copy theme to project
cp assets/custom-themes/academic.scss custom.scss

# Reference in _quarto.yml
format:
  html:
    theme: [cosmo, custom.scss]

Available themes:

• academic.scss - Clean scholarly design
• modern.scss - Contemporary web-first look
• technical.scss - Developer documentation style

6. Add Interactive Elements

For dynamic visualizations, refer to references/interactive_elements.md for complete examples.

Observable JS example:

```{ojs}
//| echo: false
viewof year = Inputs.range([2020, 2024], {value: 2022, step: 1})
filteredData = data.filter(d => d.year == year)
Plot.barY(filteredData, {x: "month", y: "value"}).plot()

### 7. Configure Search and Navigation

Enable full-text search and customize navigation:

```yaml
book:
  search:
    location: navbar
    type: overlay
  sidebar:
    style: floating
    collapse-level: 2
  page-navigation: true

8. Build and Validate

Before publishing, validate the book:

# Check all cross-references
python scripts/check_references.py

# Build all formats
quarto render

# Build specific format
quarto render --to html

9. Deploy Online

GitHub Pages (Recommended)

Initialize and deploy:

# First time setup
bash scripts/deploy_github_pages.sh init

# Subsequent deployments
bash scripts/deploy_github_pages.sh

Other Platforms

• Quarto Pub: quarto publish quarto-pub
• Netlify: Drag _book/ folder to Netlify dashboard
• Custom Server: Upload _book/ contents via FTP/SCP

Common Book Patterns

Academic Textbook

To create an academic textbook:

1. Use academic template: cp -r assets/book-template/academic/* .
2. Configure bibliography in _quarto.yml:

   bibliography: references.bib
   csl: chicago-author-date.csl
   

3. Add learning objectives to chapters
4. Include exercises with solutions appendix
5. Enable theorem environments

Technical Documentation

To create technical docs:

1. Use technical template: cp -r assets/book-template/technical/* .
2. Enable code features:

   format:
     html:
       code-copy: true
       code-fold: true
       code-tools: true
   

3. Add API reference sections
4. Include runnable examples

Multi-Author Collaboration

To set up collaborative authoring:

1. Initialize Git repository with branch protection
2. Use chapter includes for author sections
3. Set up GitHub Actions workflow: cp assets/github-actions/book-ci.yml .github/workflows/
4. Configure preview deployments for pull requests

Migration from Existing Content

To convert existing markdown to a Quarto book:

python scripts/migrate_content.py --input-dir ./my-markdown-files --output-dir ./my-book

This handles:

• Converting markdown headers to proper chapter structure
• Updating image paths and references
• Creating initial _quarto.yml configuration
• Preserving existing cross-references where possible

Bundled Resources

Scripts

• scripts/init_book.py: Initialize new book with configurable structure and options
• scripts/add_chapter.py: Add chapters with automatic configuration updates
• scripts/deploy_github_pages.sh: Automated GitHub Pages deployment workflow
• scripts/check_references.py: Validate cross-references, images, and links
• scripts/migrate_content.py: Convert existing markdown/notebooks to book format

References

• references/quarto_yml_config.md: Complete _quarto.yml configuration reference with examples
• references/themes_and_styling.md: CSS customization guide and SCSS theming
• references/deployment_guides.md: Platform-specific deployment instructions
• references/interactive_elements.md: Observable JS, Shiny, and widget integration

Assets

• assets/book-template/: Starter templates for different book types (academic, technical, general)
• assets/custom-themes/: Professional CSS/SCSS themes for various book styles
• assets/github-actions/: CI/CD workflows for automated building and publishing

Troubleshooting

Common Issues and Solutions

Book won't render

• Check _quarto.yml YAML syntax (use a YAML validator)
• Ensure all chapter files listed in configuration exist
• Verify Quarto is installed: quarto --version

Cross-references showing as broken

• Confirm label prefixes match type: fig-, sec-, tbl-, eq-
• Run validation script: python scripts/check_references.py
• Check for typos in reference labels

GitHub Pages showing 404

• If using docs/ folder: set output-dir: docs in _quarto.yml
• Add .nojekyll file to output directory
• Verify GitHub Pages is enabled in repository settings

Search not working in HTML output

• Confirm search is enabled in configuration
• Check browser console for JavaScript errors
• Ensure cookies/localStorage are not blocked

Images not displaying

• Use relative paths from chapter location
• Verify image files exist in specified paths
• Check file extensions match exactly (case-sensitive)

For additional help, consult the official Quarto documentation at https://quarto.org/docs/books/