_quarto.yml

project:
  type: book
  output-dir: _book

book:
  title: "Kates — The Definitive Guide"
  subtitle: "Kafka Advanced Testing & Engineering Suite"
  description: |
    A comprehensive guide to performance testing, chaos engineering,
    and operational resilience for Apache Kafka — from theory to practice.
  author: "Said BOUDJELDA and Contributors"
  date: today
  date-format: "MMMM YYYY"
  cover-image: assets/cover.svg
  cover-image-alt: "Kates — The Definitive Guide"
  favicon: assets/kates-mark.svg
  site-url: https://bmscomp.github.io/kates/
  google-analytics: "G-WG001H7Y0M"
  open-graph:
    image: assets/cover.png
  twitter-card:
    image: assets/cover.png
    card-style: summary_large_image
  repo-url: https://github.com/bmscomp/kates
  repo-subdir: docs/book
  repo-actions: [edit, issue]
  # An overlay: a wide modal with each match in context, opened with / or k.
  # collapse-after keeps one chapter's matches from burying the others.
  search:
    type: overlay
    keyboard-shortcut: ["/", "k"]
    limit: 50
    collapse-after: 2
  # Reader mode adds a toggle that hides the sidebar and the table of contents.
  reader-mode: true
  sidebar:
    logo: assets/kates-mark.svg
    logo-alt: "Kates"
    # Only the current part starts open.
    collapse-level: 1
    tools:
      - icon: star
        href: https://github.com/bmscomp/kates
        text: "Star Kates on GitHub"
  page-footer:
    left: "Kates — The Definitive Guide"
    # The book's license, as on the PDF's copyright page
    center: "Licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) · [Report an error](https://github.com/bmscomp/kates/issues)"
    right:
      - icon: github
        href: https://github.com/bmscomp/kates
        aria-label: "Kates on GitHub"
  back-to-top-navigation: true
  downloads: [pdf]
  # The PDF's file name, which the sidebar's download link points at. Set on
  # the book, not on format.pdf: a book ignores format.pdf.output-file and
  # names the PDF after its title, so the link and book.yml's mv both missed.
  output-file: kates-definitive-guide

  # Filenames are stable identifiers, not ordering — reading order lives
  # here and only here. Never renumber files; new chapters get slug names.
  chapters:
    - index.qmd
    # Each Part is a page, part-<slug>.md: its H1 is the Part's label in the
    # sidebar and the PDF, and its bullets list the chapters below, in this
    # order, by their H1 titles (scripts/prepare-book-render.sh checks both).
    - part: part-foundations.md
      chapters:
        - 01-introduction.md
        - 02-architecture.md
        - 03-cluster.md

    - part: part-performance-testing.md
      chapters:
        - 04-performance-theory.md
        - 05-test-types.md
        - 13-scenario-files.md
        - 10b-lab.md

    - part: part-chaos-integrity.md
      chapters:
        - 06-chaos-theory.md
        - 07-chaos-practice.md
        - 08-data-integrity.md

    - part: part-observability.md
      chapters:
        - 09-observability.md

    - part: part-deployment-operations.md
      chapters:
        - deploying-strimzi-operator.md
        - 20-installation-guide.md
        - 15-kafka-deployment.md
        - 12-deployment.md
        - compliance.md
        - 17-security.md
        - 19-multi-tenancy.md
        - 18-upgrade-playbook.md
        - 21-kafka-connect.md
        - operating-kafka-connect.md
        - 22-mirror-maker2-migration.md
        - 23-legacy-source-migration.md
        - 14-recipes.md

    - part: part-reference.md
      chapters:
        - 10-cli-reference.md
        - 11-api-reference.md
        - 16-grpc-api.md

  # No Part page here: Quarto accepts a `part:` entry in this list, but nests
  # it under its own unlinked "Appendices" label, so the sidebar shows a second,
  # collapsed "Appendices" holding the appendices. Their introduction is the
  # last section of part-reference.md instead.
  appendices:
    - appendix-a-glossary.md
    - appendix-b-troubleshooting.md
    - appendix-c-cicd.md
    - appendix-d-versions.md
    - appendix-compliance-language.md
    - appendix-ide-extensions.md
    # Unnumbered, after the appendices: the list of works cited.
    - references.md
    # Unnumbered, last: the index, generated from index-terms.txt by
    # scripts/gen-book-index.py (the PDF prints LaTeX's own index there).
    - appendix-index.md

# Citations. `[@key]` in a page cites the entry `key` in references.bib, and
# renders as its number, linked to the References page. Quarto runs citeproc
# on each page on its own, so a style that numbers by order of citation would
# restart at [1] on every page. Instead the ACM style numbers the whole
# bibliography in alphabetical order of first author, and nocite hands every
# page all of it, so a work has one number everywhere. theme/citations.lua runs
# citeproc in place of Quarto (citeproc: false) and keeps the list off every
# page but References. The style is citation-style-language/styles'
# association-for-computing-machinery.csl at c18c1a491dc6, unmodified (CC BY-SA
# 3.0).
bibliography: references.bib
csl: theme/association-for-computing-machinery.csl
nocite: |
  @*
citeproc: false
link-citations: true

format:
  html:
    # Structure is shared; each scheme only swaps the palette. Diagrams take
    # their colours from the palette too (no mermaid theme), so they follow
    # the reader's light/dark choice.
    theme:
      light: [theme/kates.scss, theme/kates-light.scss]
      dark: [theme/kates.scss, theme/kates-dark.scss]
    respect-user-color-scheme: true
    highlight-style: theme/kates-code.theme
    include-in-header: theme/head.html
    # reader.html runs after panels.html: it moves the margin's "Edit this
    # page" links, which panels.html copies into the folded contents first.
    include-after-body:
      - theme/diagrams.html
      - theme/panels.html
      - theme/reader.html
    filters:
      - path: theme/citations.lua
        at: post-render
    language:
      search-text-placeholder: "Search the book (/)"
    toc: true
    toc-depth: 3
    # The contents sit in the right margin from 1200px up and at the top of
    # the chapter below that, folded. Quarto prints both copies and shows
    # both; theme/kates.scss shows one, and theme/panels.html folds the other.
    toc-location: right-body
    # h2 entries, and the h3 entries of the section being read
    toc-expand: 1
    # Number chapters and sections (5.2), not every heading below them.
    number-depth: 2
    code-copy: true
    # Long lines scroll sideways (with edge shadows, theme/kates.scss) instead
    # of wrapping, which broke flags at hyphens and YAML indentation.
    code-overflow: scroll
  pdf:
    documentclass: scrbook
    papersize: a4
    fontsize: 11pt
    # Fonts, colours, part pages, the graphics clamp, code and output panels
    # and the cover page live in the header; the filters mark output blocks
    # and draw the cover. lualatex, for the font fallbacks.
    include-in-header: theme/pdf-header.tex
    filters:
      - theme/pdf-output.lua
      # Column widths first: it measures the Code inlines that
      # pdf-inline-code.lua turns into LaTeX.
      - theme/pdf-tables.lua
      - theme/pdf-inline-code.lua
      # The back-of-book index, from index-terms.txt (see appendix-index.md)
      - theme/index-entries.lua
      - theme/pdf-cover.lua
      - path: theme/citations.lua
        at: post-render
    pdf-engine: lualatex
    colorlinks: true
    # katesblue is the web's link colour, defined in theme/pdf-header.tex.
    linkcolor: "katesblue"
    urlcolor: "katesblue"
    filecolor: "katesblue"
    toccolor: "katesnavy"
    toc: true
    toc-depth: 2
    number-sections: true
    top-level-division: chapter
    # Captioned figures, Mermaid ones included, float to where they fit
    # instead of leaving a gap when the rest of the page is too short.
    fig-pos: "htbp"
    # The web's diagram colours come from its stylesheet, which never reaches
    # the PDF; neutral is Mermaid's own greyscale theme.
    mermaid:
      theme: neutral
    # A 160 mm text block on A4 for balanced technical tables and code listings.
    geometry:
      - top=26mm
      - bottom=28mm
      - left=25mm
      - right=25mm