Troubleshooting

This chapter addresses common problems encountered when writing technical books with Claude Code and mdBook, with solutions for each.

Claude Code Issues

Problem: Claude Code Doesn't Remember Previous Sessions

Symptom: Each session starts fresh. Previously established conventions are forgotten.

Solution: Claude Code sessions don't persist context. Always start sessions by referencing your context files:

Read CLAUDE.md and src/SUMMARY.md to understand the project.
Then read src/chapter-5.md for style context.

Maintain a CLAUDE.md file with persistent conventions that should apply to every session.

Problem: Generated Content Is Too Generic

Symptom: Content reads like boilerplate. It lacks specificity and depth.

Solutions:

  1. Provide more context:

    This is for developers who already understand [X] and need to
learn [Y] specifically for [Z use case].

  2. Specify what you don't want:

    Don't include basic explanations of [fundamental concept] —
readers already know this.

  3. Use pushback:

    This is too generic. A senior developer implementing this in
production would need to know [specific concerns]. Rewrite
with those details.

Problem: Inconsistent Voice or Terminology

Symptom: The chapter uses different terms or a different tone than earlier chapters.

Solutions:

  1. Reference existing content:

    Read chapters 2 and 3 first. Match their voice and terminology exactly.

  2. Specify terminology:

    Use "endpoint" not "route." Use "request handler" not "controller."

  3. Fix retroactively:

    Review this chapter for terminology consistency with chapter 3.
List any differences and correct them.

Problem: Code Examples Don't Compile

Symptom: Code examples have syntax errors, missing imports, or don't run.

Solutions:

  1. Request complete examples:

    All code examples must be complete and compilable. Include all
necessary imports. Don't assume context.

  2. Request verification:

    Before finalizing, verify each code example compiles. Fix any
issues and explain what was wrong.

  3. Use external files: Store examples in separate files that you can test using the include directive: {{#include ../examples/chapter5/auth.rs}}

Problem: Content Scope Keeps Expanding

Symptom: Each iteration adds more tangential content. The chapter grows unfocused.

Solutions:

  1. Define scope explicitly:

    This chapter covers ONLY: [list]
It explicitly does NOT cover: [list]

  2. Reject additions:

    That addition is out of scope for this chapter. It belongs in
chapter 8. Don't include it here.

  3. Set length targets:

    This section should be 300-400 words. Don't expand beyond that.

mdBook Build Issues

Problem: "File not found" Errors

Symptom: mdbook build reports files referenced in SUMMARY.md don't exist.

Solution: Ensure every path in SUMMARY.md has a corresponding file:

# Check for missing files
mdbook build 2>&1 | grep "not found"

Either create the missing files or remove the references from SUMMARY.md.

Symptom: Links to other chapters produce 404 errors.

Solution: Use relative paths from the current file's location:

<!-- From src/part1/chapter1.md to src/part2/chapter5.md -->
See [Chapter 5](../part2/chapter5.md)

<!-- From src/chapter1.md to src/chapter5.md -->
See [Chapter 5](./chapter5.md)

Verify links by building:

mdbook build 2>&1 | grep -i warning

Problem: Code Blocks Not Highlighting

Symptom: Code appears as plain text without syntax highlighting.

Solutions:

  1. Specify the language:

    ```rust
fn main() {}
```

    Not:

    ```
fn main() {}
```

  2. Check language identifier: Use standard identifiers: rust, python, javascript, typescript, go, java, etc.

  3. Check for malformed blocks: Ensure exactly three backticks, no spaces before them.

Problem: Build Is Slow

Symptom: mdbook build takes a long time, especially in CI.

Solutions:

  1. Cache mdBook binary in CI:

    - uses: actions/cache@v4
  with:
    path: ~/.cargo/bin/mdbook
    key: mdbook-${{ runner.os }}

  2. Use mdbook serve during development: Incremental rebuilds are faster than full builds.

  3. Reduce image sizes: Large images slow builds and page loads. Compress before including.

Problem: Search Not Working

Symptom: Search returns no results or the search box is missing.

Solutions:

  1. Ensure search is enabled:

    [output.html.search]
enable = true

  2. Rebuild from scratch:

    rm -rf book/
mdbook build

  3. Check browser console: JavaScript errors can prevent search from initializing.

Problem: Theme Issues

Symptom: Dark mode doesn't work, wrong colors, theme switcher missing.

Solution: Configure themes in book.toml:

[output.html]
default-theme = "light"
preferred-dark-theme = "ayu"

Available themes: light, rust, coal, navy, ayu

Content Issues

Problem: Chapters Are Uneven Lengths

Symptom: Some chapters are 500 words, others are 5000 words.

Solutions:

  1. Set length targets per chapter:

    This chapter should be approximately 3000 words.

  2. Split long chapters: If a chapter exceeds 5000 words, consider splitting into two chapters.

  3. Expand thin chapters:

    This chapter is too brief. What additional topics within
scope should be covered? What details are missing?

Problem: Readers Get Lost

Symptom: Feedback indicates readers can't follow the progression.

Solutions:

  1. Add chapter previews: Begin each chapter with what will be covered.

  2. Add section summaries: End each major section with key takeaways.

  3. Add cross-references:

    As we covered in [Chapter 3](./chapter3.md)...

  4. Check prerequisites: Each chapter should state what readers need to know first.

Problem: Code Examples Don't Match Text

Symptom: The prose describes one thing but the code shows something different.

Solutions:

  1. Review alignment:

    Review this section. Does the text accurately describe what
the code example shows? Fix any discrepancies.

  2. Update together: When changing code examples, immediately update the surrounding prose.

  3. Use inline comments: Key code lines should have comments matching the textual explanation.

Deployment Issues

Problem: GitHub Pages Not Updating

Symptom: Pushes don't appear on the deployed site.

Solutions:

  1. Check Actions tab: Verify the workflow ran successfully.

  2. Check Pages settings: Ensure source is configured correctly.

  3. Clear browser cache: Old versions may be cached.

  4. Verify build output: Check that the built files are in the correct directory.

Problem: Custom Domain Not Working

Symptom: Custom domain returns 404 or wrong site.

Solutions:

  1. Verify DNS:

    dig yourdomain.com

  2. Check CNAME file: Must contain only the domain, no protocol:

    book.yourdomain.com

    Not:

    https://book.yourdomain.com

  3. Wait for propagation: DNS changes can take up to 48 hours.

  4. Re-enable HTTPS: After DNS propagates, re-enable HTTPS in repo settings.

Problem: Large Repository Size

Symptom: Repository grows large, clones are slow.

Solutions:

  1. Don't commit build output: Add book/ to .gitignore unless using docs-folder deployment.

  2. Optimize images: Compress images before committing. Consider storing large assets elsewhere.

  3. Clean history: If large files were accidentally committed:

    git filter-branch --tree-filter 'rm -rf book/' HEAD

    (Use with caution; rewrites history.)

Process Issues

Problem: Lost Work Between Sessions

Symptom: Decisions and conventions are forgotten between sessions.

Solution: Document everything in persistent files:

  • CLAUDE.md: Conventions, terminology, style rules
  • STATUS.md: Current progress, open questions
  • DECISIONS.md: Key decisions and their rationale

Read these files at the start of each session.

Problem: Inconsistent Quality Across Chapters

Symptom: Some chapters are polished, others are rough.

Solutions:

  1. Use a checklist: Apply the same quality checklist to every chapter before considering it complete.

  2. Batch similar improvements: Rather than finishing chapters sequentially, do all technical reviews together, all comprehensiveness reviews together, etc.

  3. Track status: Maintain a status document showing which chapters have completed which review stages.

Problem: Scope Creep

Symptom: The book grows beyond its original intent, pushing back deadlines.

Solutions:

  1. Define scope upfront: Document what the book covers and explicitly what it doesn't.

  2. Maintain a "future editions" list: When good ideas emerge that are out of scope, capture them for later rather than adding them now.

  3. Review against scope regularly: Before each chapter, verify it's within the original scope.

Getting Help

If you encounter issues not covered here:

  1. mdBook documentation: rust-lang.github.io/mdBook
  2. mdBook issues: github.com/rust-lang/mdBook/issues
  3. Claude Code help: github.com/anthropics/claude-code/issues