Skip to content

Adding a New Book Chapter

Duration: 45 minutes Level: Intermediate (Contributor) Target: authors extending one of the three FCC books, the Guidebook, or any publication profile

This tutorial walks you through adding a new chapter to the FCC publication pipeline. You will learn where chapter source lives, how to wire a new chapter into the _quarto.yml configuration, how to embed mermaid diagrams with figure metadata, and how to verify the chapter renders cleanly across all four output formats (PDF, EPUB, DOCX, HTML).

Where chapter source lives

Each book lives in its own directory under docs/. Chapters are ordered markdown files named ch##_topic.md:

Book Directory
Book 1: Understanding FCC docs/books/book1_understanding_fcc/
Book 2: Building with FCC docs/books/book2_building_with_fcc/
Book 3: Advanced FCC docs/books/book3_advanced_fcc/
Guidebook docs/guidebook/

Chapter files must match the glob ch*_*.md — that is the pattern build_all.sh uses to enumerate chapters. For example, ch07_patterns.md will be picked up; chapter-7-patterns.md will not.

Chapter numbers control ordering. Use two digits (ch07, not ch7) so the shell glob sorts lexicographically correctly. Gaps are allowed — you can leave ch06 open and skip to ch07.

Step 1: create the chapter stub

Pick a slot and create the file. Example — adding a new chapter to Book 2 about GraphRAG:

cat > docs/books/book2_building_with_fcc/ch15_graphrag.md <<'EOF'
# GraphRAG

## Overview

GraphRAG extends classical RAG with graph-of-thought expansion over the FCC
knowledge graph. This chapter walks through the six-stage pipeline and shows
how to compose it with personas and Zachman-cell filters.

## Architecture

<!-- fig-meta: {"caption": "GraphRAG 6-stage pipeline", "slug": "graphrag-pipeline", "width": "80%"} -->
```mermaid
flowchart LR
    Seed[Seed retrieval] --> BFS[BFS walk]
    BFS --> Zach[Zachman filter]
    Zach --> Score[Persona scoring]
    Score --> LYRA[LYRA augment]
    LYRA --> Ctx[Context assembly]

Six stages

  1. Seed retrieval — SemanticRetriever surfaces candidate nodes.
  2. BFS walk — traverse outgoing edges up to max_hops.
  3. Zachman filter — narrow to the target enterprise perspective.
  4. Persona scoring — deterministic [0.1, 1.0] per node.
  5. LYRA augment — cross-namespace concept expansion.
  6. Context assembly — roll up into an LLM-ready string.

Code example

from fcc.rag.graphrag import GraphRAG
from fcc.knowledge.builders import build_full_fcc_graph

pipe = GraphRAG(knowledge_graph=build_full_fcc_graph())
result = pipe.query("research crafter", max_hops=2)

Summary

... EOF 

### Front matter

Book chapters do **not** use YAML front matter — they are standalone Markdown
files consumed by Pandoc directly. Metadata (title, author) is set via
`--metadata` flags in `build_all.sh`.

If you want per-chapter metadata (e.g. an estimated reading time), embed it
as an HTML comment that human readers and Pandoc both ignore:

```markdown
<!-- reading-time: 20 minutes -->
<!-- audience: advanced -->

Step 2: wire into _quarto.yml (optional)

_quarto.yml is used by the Quarto-rendered publications (presentations, reference cards, patent profile, academic profile). Book chapters rendered via Pandoc directly do not require a _quarto.yml edit — they are picked up automatically by the docs/books/book*/ch*_*.md glob in build_all.sh.

You only edit _quarto.yml if the chapter belongs to a Quarto-rendered publication. Example for the combined book config:

# publications/_quarto.yml
project:
  type: book

book:
  title: "FCC Framework — Combined Book"
  chapters:
    - index.qmd
    - part: "Part IX — v1.5.0 Pillars"
      chapters:
        - chapters/arch/graphrag.qmd
        - chapters/arch/crdt.qmd
        - chapters/arch/bidirectional-federation.qmd
        - chapters/arch/six-pillars.qmd
        - chapters/arch/ch15-graphrag-deep-dive.qmd   # <- NEW

Chapters listed under book.chapters render in the declared order — the ch##_ numeric prefix is not enforced by Quarto.

Step 3: embed mermaid diagrams

Mermaid blocks are ordinary fenced code blocks:

```mermaid
flowchart LR
    A --> B --> C
```

The publication pipeline pre-renders these via render_mermaid.py into SVG + PNG twin trees. At render time the fenced block is replaced with an image reference; at read time (e.g. under mkdocs or GitHub) the block renders natively.

Figure metadata

Attach a fig-meta HTML comment immediately above the mermaid block to supply caption, slug, and width:

<!-- fig-meta: {"caption": "GraphRAG 6-stage pipeline", "slug": "graphrag-pipeline", "width": "80%"} -->

Fields:

Field Purpose
caption Figure caption rendered under the diagram in PDF/DOCX
slug Image filename stem (default: ch##_topic_N)
width Quarto/Typst width (e.g. "80%", "4in")
attr Extra Pandoc attributes ({#fig-graphrag .nostretch})

When fig-meta is missing, the pipeline uses the auto-generated slug and no caption.

Mermaid syntax gotchas

Three patterns the v1.5.2 release memory confirms will break mmdc:

  • Parens + semicolons inside classDiagram member text. Simplify to plain words.
  • {{PLACEHOLDER}} markers inside class members. Mermaid's parser interprets them as interpolations — use plain text like TRANSLATE marker.
  • <br/> inside sequenceDiagram Notes. Not supported; use spaces.

If the chapter references a diagram file already in docs/architecture/ (e.g. a sequence diagram), link to it rather than duplicating the source:

::: {.callout-note}
Sequence diagram: `docs/architecture/sequence-diagrams/graphrag-zachman-filter.md`
:::

Step 4: run the pipeline locally

Fast iteration — just diagrams

make pub-diagrams

This pre-renders the mermaid blocks into both SVG and PNG trees under publications/_build/processed-svg/ and _build/processed-png/. Inspect your chapter's images in publications/_output/assets/diagrams/.

One book rebuild

make pub-books

Renders all four books — PDF, EPUB, DOCX, HTML. Takes about 3 minutes on a warm cache.

Full rebuild

make pub-all

Rebuilds every publication. Use this before submitting a PR that touches book chapters.

Step 5: verify the chapter

Render count

After make pub-books, inspect the artifact:

ls -la publications/_output/books/book2-building-with-fcc.*
# Expect: .pdf .epub .docx .html

Each file should be >1 MB (book with diagrams). A suspiciously small PDF usually means the chapter was skipped — check the stderr of build_all.sh.

PDF visual check

Open publications/_output/books/book2-building-with-fcc.pdf and navigate to the table of contents. Your chapter should appear with the correct title and page number. Mermaid diagrams should render as vector SVG (scalable without pixelation).

DOCX visual check

DOCX is the format most likely to have subtle issues. Open publications/_output/books/book2-building-with-fcc.docx in Word or LibreOffice. Mermaid diagrams should appear as PNG images with captions.

If images are missing, run make pub-diagrams to re-render the PNG tree and retry.

HTML visual check

xdg-open publications/_output/books/book2-building-with-fcc.html  # Linux
open publications/_output/books/book2-building-with-fcc.html      # macOS

Internal cross-references should resolve (click a heading in the ToC).

Step 6: cross-references

Within the same book

Pandoc generates heading ids automatically from heading text. Cross-reference them with standard markdown:

See [the overview section](#overview) for context.

For explicit ids, use the {#my-id} Pandoc attribute:

## Overview {#graphrag-overview}

...

See [the overview](#graphrag-overview).

Across books

Cross-book references do not resolve in the current pipeline — each book is a separate Pandoc invocation. Use textual references instead:

See Book 1, Chapter 5 (Personas) for the R.I.S.C.E.A.R. overview.

To tutorials or external docs

Link to mkdocs paths under docs/:

For a runnable walkthrough, see the
[GraphRAG deep-dive tutorial](../../tutorials/advanced-capabilities/graphrag-deep-dive.md).

These resolve correctly in the mkdocs-rendered site. In PDF/DOCX output, the pipeline converts them to textual footnotes — the link target is preserved, but the reader needs the web site for the live link.

Step 7: checklist before submitting

  • Chapter file follows ch##_topic.md naming
  • First line is # Chapter Title (Pandoc uses this for the ToC entry)
  • No YAML front matter (books don't use it)
  • All mermaid blocks have fig-meta comments with captions
  • make pub-diagrams completes cleanly — no errors in stdout
  • make pub-books produces all four formats without FAILED markers
  • PDF ToC includes your chapter with correct page numbers
  • DOCX renders mermaid diagrams as PNG images with captions
  • No broken internal cross-references
  • Chapter fits the book's voice (book 1 = conceptual, book 2 = hands-on, book 3 = advanced)

Tips for a good chapter

  • Open with the problem. What is the reader stuck on? Start the chapter by naming it, not by defining terms.
  • Keep code blocks runnable. A chapter is not a reference page — the reader will copy-paste. Include imports; avoid pseudocode.
  • End with "Summary" and "Next" sections. Readers skim chapter endings more than openings. Give them a recap and a next destination.
  • Mermaid for structure, prose for detail. Use diagrams when relationships between components matter; use prose when sequencing matters.
  • Three H2 sections minimum, seven maximum. Too few sections feel monolithic; too many fragment the narrative.

Extending other profiles

The same mechanics apply to non-book publications, with minor differences:

  • Guidebook — add under docs/guidebook/ with the same ch##_topic.md naming. Automatically picked up by pub-books build step.
  • Executive — add under docs/decision-makers/. Requires explicit listing in build_all.sh under EXEC_CHAPTERS_SVG and EXEC_CHAPTERS_PNG.
  • Academic — add under docs/for-educators/. Same as executive, with ACAD_CHAPTERS_* lists.
  • Reference cards — create a new .qmd under publications/reference-cards/. Automatically picked up by the for card in reference-cards/*.qmd loop.
  • Patent — add under docs/patent/ and reference in publications/_quarto-patent.yml. Patent changes require counsel review before commit.

Summary

In this tutorial you learned how to:

  • Create a chapter stub at the correct path and naming convention
  • Embed mermaid diagrams with fig-meta captions
  • Wire the chapter into _quarto.yml (only required for Quarto-rendered profiles)
  • Run the pipeline locally with make pub-diagrams + make pub-books
  • Verify the chapter renders cleanly in all four output formats
  • Cross-reference within a book, across books, and to external docs

Next steps

  • Read publication pipeline mechanics for the full pipeline internals
  • Browse existing chapters under docs/books/book2_building_with_fcc/ for voice and structure examples
  • Send the PR with a screenshot of your PDF's ToC entry so reviewers can verify the chapter landed correctly
  • Publication pipeline mechanics — docs/tutorials/publications/publication-pipeline-mechanics.md
  • Main Quarto config — publications/_quarto.yml
  • Build script — publications/scripts/build_all.sh
  • Mermaid renderer — publications/scripts/render_mermaid.py