A template repository for creating books with Quarto. This template provides everything you need to quickly start writing your own book.

• 📚 Book-ready structure with sample chapters and references
• 🎨 Customizable themes supporting light and dark modes
• 🚀 Automatic deployment to GitHub Pages via GitHub Actions
• 🔗 Automated link checking to ensure all URLs are reachable
• 📄 Multiple output formats including HTML, PDF, EPUB, and DOCX
• 📑 Bibliography support with BibTeX integration
• 🔢 Automatic numbering of sections and cross-references
• 💅 Custom CSS for styling your book
• 🔍 PR Preview with change highlighting for pull requests
• ✅ Automated checks including spell checking and linting
• 🤖 GitHub Copilot integration with custom setup steps
• 📝 AI-powered issue summaries for new issues

1. Click the “Use this template” button at the top of this repository
2. Name your new repository and create it
3. Clone your new repository to your local machine

git clone https://github.com/YOUR-USERNAME/YOUR-REPO.git
cd YOUR-REPO

You need to have Quarto installed. Download it from quarto.org/docs/get-started.

To verify Quarto is installed:

quarto --version

1. Edit _quarto.yml to update:

   • Book title and author
   • Repository URL
   • Chapter list
   • Theme and styling options

2. Modify index.qmd to create your book’s homepage/introduction

3. Edit or create chapters (.qmd files):

   • Modify chapter1.qmd and chapter2.qmd as needed
   • Create new chapters and add them to the chapters list in _quarto.yml

4. Add references to references.bib in BibTeX format

5. Customize styling in styles.css

To preview your book with live reload during development:

quarto preview

This will open your book in a web browser and automatically refresh when you make changes.

To render the complete book:

quarto render

The output will be generated in the docs/ directory.

This template includes a GitHub Actions workflow (.github/workflows/publish.yml) that automatically builds and publishes your book to GitHub Pages when you push to the main branch.

1. Enable GitHub Pages in your repository:

   • Go to Settings → Pages
   • Under “Build and deployment”, set Source to “GitHub Actions”

2. Push to main branch:

   git add .
   git commit -m "Initial book setup"
   git push origin main

3. Wait for the workflow to complete (check the Actions tab)

4. Access your book at: https://YOUR-USERNAME.github.io/YOUR-REPO/

This template includes several automated workflows to enhance your development experience:

Automatically builds and deploys your book to GitHub Pages when you push to the main branch.

Triggers: Push to main branch, manual dispatch

Creates a preview deployment for pull requests with:

• Change detection and highlighting
• DOCX files with tracked changes
• Visual indicators for modified chapters
• Banner showing what changed in the PR

Triggers: PR opened, reopened, synchronized, closed, labeled, or unlabeled

Labels:

• Add no-preview-highlights label to disable change highlighting if it’s glitchy

Runs automated spell checking on pushes and pull requests to maintain content quality.

Triggers: Push to main, pull requests

Checks R code style and quality using the lintr package.

Triggers: Push to main/master, pull requests

Note: Only runs if your project contains R code.

Configures the GitHub Copilot coding agent’s environment with Quarto and TinyTeX.

Triggers: Workflow dispatch, changes to the setup file

Automatically generates AI-powered summaries for newly opened issues.

Triggers: New issue opened

Permissions required: The models: read permission for AI inference

Validates that all books and articles in bibliography files meet DOI requirements:

• Every book and article must have a DOI field
• Every DOI must resolve to a valid URL
• Reference information is checked against DOI metadata for consistency

Triggers: Push to main, pull requests, manual dispatch

Note: This helps maintain high-quality bibliographic references and ensures all citations are properly traceable.

.
├── _quarto.yml              # Main configuration file
├── index.qmd                # Book homepage/introduction
├── chapter1.qmd             # Sample chapter 1
├── chapter2.qmd             # Sample chapter 2
├── references.qmd           # References page
├── references.bib           # BibTeX bibliography
├── styles.css               # Custom CSS styles
├── lychee.toml              # Link checker configuration
├── .gitignore              # Git ignore file
├── LICENSE                  # CC0 1.0 Universal License
├── README.md               # This file
└── .github/
    ├── scripts/             # Scripts for workflows
    │   ├── add-home-banner.py
    │   ├── check-bibliography-dois.R
    │   ├── create-docx-tracked-changes.py
    │   ├── detect-changed-chapters.py
    │   ├── highlight-html-changes.py
    │   └── inject-preview-metadata.py
    └── workflows/           # GitHub Actions workflows
        ├── publish.yml      # Build and deploy to GitHub Pages
        ├── preview.yml      # PR preview with change highlighting
        ├── check-spelling.yaml  # Spell checking
        ├── lint-project.yaml    # R code linting
        ├── copilot-setup-steps.yml  # GitHub Copilot setup
        ├── summary.yml      # AI-powered issue summaries
        ├── check-links.yml  # URL reachability checker workflow
        └── check-bibliography-dois.yml  # Bibliography DOI validation

This template includes two GitHub Actions workflows:

Automatically builds and deploys your book to GitHub Pages when you push to the main branch.

Automatically checks that all URLs in your book are reachable:

• Runs on: Push to main, pull requests, weekly schedule (Mondays at 9:00 UTC), and manual trigger
• Checks: All links in .qmd, .md, and .html files
• Reports: Workflow fails if broken links are detected. Check the workflow logs for details on which links are broken.
• Configuration: Customize behavior in lychee.toml
• Manual override: Add the links checked by hand label to a PR to skip the automated link check

To manually trigger the link checker:

1. Go to the Actions tab in your repository
2. Select “Check Links” workflow
3. Click “Run workflow”

Quarto uses markdown with extensions. Here are some quick tips:

# Chapter Title
## Section
### Subsection

```python
print("Hello, World!")
```

Inline: $E = mc^2$

Display:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Reference a citation: @citationkey

Reference figures, tables, and sections using labels:

See @fig-example for details.

For more details, see the Quarto documentation.

Edit the format.html.theme section in _quarto.yml:

format:
  html:
    theme:
      light: cosmo  # Try: cosmo, flatly, litera, minty, etc.
      dark: darkly  # Try: darkly, cyborg, slate, superhero, etc.

1. Create a new .qmd file (e.g., chapter3.qmd)
2. Add it to the chapters list in _quarto.yml:

book:
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd
    - chapter3.qmd  # Your new chapter
    - references.qmd

Add your custom styles to styles.css. These will override the default theme styles.

This template is released under the CC0 1.0 Universal License, which means you can freely use, modify, and distribute it without any restrictions.

This template is based on the structure of the UCD-SERG Lab Manual, which was adapted from the Benjamin-Chung Lab Manual.

• Quarto Documentation
• Quarto Community
• GitHub Pages Documentation

Feel free to open issues or submit pull requests to improve this template!