Setup and Configuration

This chapter covers the technical prerequisites for using Claude Code as a book authoring tool. The setup process involves installing Claude Code, configuring mdBook, and establishing a project structure optimized for iterative writing.

Prerequisites

Before beginning, ensure you have:

  • Node.js 18+ or access to Claude Code through Anthropic's distribution
  • Rust and Cargo (for mdBook installation)
  • Git (for version control)
  • A text editor with Markdown support

Installing Claude Code

Claude Code is Anthropic's command-line interface for Claude. Install it following the official documentation at claude.ai/claude-code.

Verify the installation:

claude --version

Claude Code operates in your terminal with full access to your filesystem, enabling it to read existing content, create new files, and modify drafts directly.

Installing mdBook

mdBook is a command-line tool for creating books from Markdown files. Install it via Cargo:

cargo install mdbook

Verify the installation:

mdbook --version

For additional functionality, consider these plugins:

# Syntax highlighting for more languages
cargo install mdbook-mermaid

# Table of contents in each page
cargo install mdbook-toc

# Search functionality enhancement
cargo install mdbook-pagetoc

Project Initialization

Create a new book project:

mdbook init my-technical-book
cd my-technical-book

This creates the basic structure:

my-technical-book/
├── book.toml
└── src/
    ├── SUMMARY.md
    └── chapter_1.md

Configuration

The book.toml file controls your book's metadata and build settings. A production-ready configuration:

[book]
authors = ["Your Name"]
language = "en"
multilingual = false
src = "src"
title = "Your Book Title"
description = "A concise description for metadata and SEO"

[build]
build-dir = "book"
create-missing = false

[output.html]
default-theme = "light"
preferred-dark-theme = "ayu"
git-repository-url = "https://github.com/yourorg/your-book"
edit-url-template = "https://github.com/yourorg/your-book/edit/main/{path}"

[output.html.fold]
enable = true
level = 1

[output.html.search]
enable = true
limit-results = 30
teaser-word-count = 30
use-hierarchical = true

Key settings:

  • create-missing = false prevents mdBook from creating placeholder files, ensuring your SUMMARY.md remains the source of truth
  • edit-url-template adds "suggest an edit" links to each page
  • fold.level = 1 collapses sidebar sections by default, improving navigation for large books

Claude Code Configuration

Claude Code uses a CLAUDE.md file in your project root for persistent context. Create one tailored for book authoring:

# Project: Technical Book

This is an mdBook project for technical documentation.

## Structure
- `src/SUMMARY.md` - Table of contents (source of truth for chapter order)
- `src/*.md` - Individual chapter files
- `book.toml` - mdBook configuration

## Writing Standards
- Use ATX-style headers (# not underlines)
- Code blocks must specify language for syntax highlighting
- Keep paragraphs focused on single concepts
- Use second person ("you") for instructions
- Use present tense for descriptions

## Terminology
- "Claude Code" not "Claude" when referring to the CLI tool
- "mdBook" not "mdbook" or "Mdbook"
- Define acronyms on first use

## Chapter Template
Each chapter should include:
1. Opening paragraph stating the chapter's purpose
2. Conceptual explanation
3. Practical examples
4. Common pitfalls or considerations
5. Summary or transition to next chapter

This file persists across Claude Code sessions, maintaining consistency throughout your writing project.

Version Control Setup

Initialize git and create a .gitignore:

git init

Create .gitignore:

# Build output
book/

# Editor files
*.swp
*~
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

Make your initial commit:

git add .
git commit -m "Initial book structure"

Development Workflow

Build and serve your book locally during development:

mdbook serve --open

This starts a local server at http://localhost:3000 with live reload. Changes to any .md file trigger an automatic rebuild.

For Claude Code sessions, keep this running in a separate terminal. You can ask Claude Code to make changes and immediately see the results in your browser.

Verifying the Setup

Test your environment by asking Claude Code to make a small change:

Add a brief placeholder paragraph to chapter_1.md explaining
that this content will be expanded.

Then verify:

  1. The file was modified correctly
  2. mdBook rebuilt automatically
  3. The change appears in your browser

Your environment is ready for book authoring when all three steps succeed.

Next Steps

With the technical foundation in place, the next chapter covers project structure — organizing chapters, managing assets, and planning your book's architecture before writing begins.