Project Structure

A well-organized project structure is the foundation for maintainable technical documentation. This chapter covers the organization patterns that work best with Claude Code's file-based workflow.

Directory Layout

The recommended structure for a technical book:

your-book/
├── book.toml
├── CLAUDE.md
├── .gitignore
├── src/
│   ├── SUMMARY.md
│   ├── introduction.md
│   ├── part-1/
│   │   ├── chapter-1.md
│   │   ├── chapter-2.md
│   │   └── chapter-3.md
│   ├── part-2/
│   │   ├── chapter-4.md
│   │   └── chapter-5.md
│   ├── appendices/
│   │   ├── appendix-a.md
│   │   └── appendix-b.md
│   └── images/
│       ├── diagram-1.png
│       └── screenshot-1.png
├── examples/
│   ├── chapter-1/
│   │   └── complete-example.rs
│   └── chapter-4/
│       └── demo-project/
└── scripts/
    └── validate-examples.sh

The SUMMARY.md File

SUMMARY.md is the table of contents and the source of truth for your book's structure. mdBook generates navigation from this file.

# Summary

[Introduction](./introduction.md)

# Part 1: Foundations

- [Core Concepts](./part-1/chapter-1.md)
- [Architecture](./part-1/chapter-2.md)
- [Configuration](./part-1/chapter-3.md)

# Part 2: Advanced Topics

- [Performance](./part-2/chapter-4.md)
- [Scaling](./part-2/chapter-5.md)

---

[Appendix A: Reference](./appendices/appendix-a.md)
[Appendix B: Glossary](./appendices/appendix-b.md)

Key formatting rules:

  • Part headers use # Part Name syntax
  • Chapter links use - [Title](./path.md) syntax
  • Separators (---) create visual breaks in navigation
  • Unnumbered appendices omit the - prefix

File Naming Conventions

Consistent naming helps both Claude Code and human collaborators navigate the project:

Chapter files:

  • Use kebab-case: getting-started.md, not GettingStarted.md
  • Be descriptive: error-handling.md, not chapter-7.md
  • Keep names short but meaningful: auth.md or authentication.md, not a.md

Image files:

  • Include chapter context: ch3-architecture-diagram.png
  • Use descriptive names: oauth-flow-sequence.png, not image1.png
  • Prefer PNG for diagrams, JPG for screenshots

Code example directories:

  • Mirror chapter structure: examples/chapter-3/
  • Use project-appropriate names: examples/auth-demo/

Organizing Large Books

Books exceeding ten chapters benefit from part-based organization:

src/
├── SUMMARY.md
├── introduction.md
├── part-1-basics/
│   ├── installation.md
│   ├── first-project.md
│   └── core-concepts.md
├── part-2-intermediate/
│   ├── advanced-config.md
│   ├── testing.md
│   └── debugging.md
└── part-3-advanced/
    ├── performance.md
    ├── scaling.md
    └── internals.md

This structure:

  • Groups related chapters for easier navigation
  • Allows parallel work on different parts
  • Makes the scope of each section clear to Claude Code

Managing Code Examples

Code examples require special consideration. Two patterns work well:

Inline Examples

For short examples (under 30 lines), include code directly in the Markdown:

```rust
fn main() {
    println!("Hello, world!");
}
```

External Examples

For longer examples or complete projects, store them externally and reference them:

The complete implementation is available in
[`examples/chapter-5/auth-server/`](../examples/chapter-5/auth-server/).

Here's the key function:

\`\`\`rust
{{#include ../examples/chapter-5/auth-server/src/main.rs:authenticate}}
\`\`\`

mdBook's {{#include}} directive pulls code from external files, keeping examples testable and maintainable.

Working with Claude Code

Structure your project to maximize Claude Code's effectiveness:

Keep files focused. Each chapter file should cover one coherent topic. Files exceeding 500 lines become difficult to discuss and modify in conversation.

Use clear boundaries. When asking Claude Code to modify content, reference files by name: "Update the authentication section in src/part-2/auth.md" rather than "update the authentication section."

Maintain CLAUDE.md. Document structural decisions, naming conventions, and style requirements. Claude Code reads this file at the start of each session.

Example CLAUDE.md section for structure:

## Project Structure

- Chapters are in `src/` organized by part
- Code examples go in `examples/` mirroring chapter structure
- Images go in `src/images/` with chapter prefixes
- New chapters must be added to SUMMARY.md manually

## File Naming

- Chapters: kebab-case, descriptive names
- Images: chapter-prefix-description.png
- Examples: chapter-number/project-name/

Planning Chapter Dependencies

Before writing, map chapter dependencies. A chapter that references concepts from another chapter creates a dependency:

introduction.md (no dependencies)
    ↓
installation.md (no dependencies)
    ↓
core-concepts.md (depends: installation)
    ↓
first-project.md (depends: core-concepts)
    ↓
testing.md (depends: first-project, core-concepts)

This map helps you:

  • Write chapters in logical order
  • Know when to add cross-references
  • Identify circular dependencies early

When working with Claude Code, mention dependencies explicitly: "This chapter assumes the reader has completed the installation chapter and understands the core concepts from chapter 3."

Version Control Practices

Commit strategically during book development:

Commit complete chapters. Avoid committing half-written chapters. If a writing session ends mid-chapter, use a WIP commit or stash.

Commit after successful builds. Run mdbook build before committing to ensure no broken links or syntax errors.

Use meaningful commit messages:

git commit -m "Add authentication chapter with OAuth2 examples"
git commit -m "Expand error handling section with recovery patterns"
git commit -m "Fix broken link in chapter 3"

Branch for major changes. When restructuring or rewriting significant portions, use a feature branch:

git checkout -b rewrite-part-2
# ... make changes ...
git checkout main
git merge rewrite-part-2

Validating Structure

Before significant writing sessions, validate your structure:

# Check for broken internal links
mdbook build 2>&1 | grep -i "warning"

# Verify all SUMMARY.md entries exist
mdbook build

# Preview the full structure
mdbook serve --open

Fix structural issues before writing content. Broken links and missing files create confusion during Claude Code sessions.

Next Steps

With a solid project structure in place, the next chapter covers writing strategy — how to craft prompts that produce useful first drafts for each chapter.