Project Initialization

Initialize Book Project Structure

Quick Start

make init-bp

This installs all dependencies and runs the interactive project initializer. It is the recommended way to set up a new book project.

Alternatively, step by step:

make lock-install
make init-bp

See the Makefile Overview for all available targets.

---

What Happens During Initialization

You will be prompted to enter:

• Project name (used for folder and export base name)
• Project description (used in pyproject.toml)
• Book title (used in export metadata)
• Author name (used in export metadata)
• Publication year (default: 2025)
• Language code (default: en)

These values are automatically applied to:

File	What Gets Updated
pyproject.toml	Project name and description
config/metadata.yaml	Title, author, description, date, language
config/init-settings.yaml	Created with the default project structure (if not present)

---

Example Prompt Flow

Enter your project name (e.g., 'ai-for-everyone'): my-book
Enter a short description of your project: A journey into friendly AI.
Enter your book title: AI for Everyone
Enter the author's name: Asterios Raptis
Enter publication year [2025]: 2025
Enter language code [en]: en

Result in pyproject.toml:

name = "my-book"
description = "A journey into friendly AI."

Result in config/metadata.yaml:

title: "AI for Everyone"
author: "Asterios Raptis"
description: "A journey into friendly AI."
date: "2025"
language: "en"

---

What Gets Created

The initializer creates directories and files based on config/init-settings.yaml. If that file does not exist, built-in defaults are used and the file is created automatically for future customization.

Default directories:

• manuscript/chapters, manuscript/front-matter, manuscript/back-matter
• assets/covers, assets/author, assets/figures/diagrams, assets/figures/infographics
• config, config/data, output

Default files:

• Chapter placeholders (01-chapter.md, 02-chapter.md)
• Front matter: toc.md, toc-print.md, preface.md, foreword.md
• Back matter: about-the-author.md, acknowledgments.md, appendix.md, bibliography.md, epilogue.md, glossary.md, imprint.md
• Config: metadata.yaml, styles.css, keywords.md, amazon-kdp-info.md, book-description.html, cover page texts
• README.md, LICENSE

---

Customizing the Project Structure

After the first run, you will find config/init-settings.yaml in your project. Edit it to control what gets created on subsequent runs.

Full control (replace defaults entirely):

directories:
  - manuscript/chapters
  - manuscript/front-matter
  - config
  - output

files:
  - manuscript/chapters/01-intro.md
  - manuscript/front-matter/toc.md
  - README.md

Additive (extend defaults):

include_directories:
  - manuscript/exercises
  - assets/audio

include_files:
  - manuscript/chapters/03-chapter.md
  - manuscript/chapters/04-chapter.md

Subtractive (remove from defaults):

exclude:
  - manuscript/back-matter/appendix.md
  - manuscript/back-matter/glossary.md
  - config/amazon-kdp-info.md
  - config/book-description.html

Combined (extend and exclude at the same time):

include_directories:
  - manuscript/exercises

include_files:
  - manuscript/chapters/03-chapter.md

exclude:
  - manuscript/back-matter/appendix.md
  - config/amazon-kdp-info.md

If init-settings.yaml is deleted or contains invalid YAML, the initializer falls back to built-in defaults and logs a warning.

---

Cleaning Up Excluded Items

If you exclude items in init-settings.yaml that already exist on disk, the initializer will warn you:

WARNING: 2 excluded items still exist on disk. Run with --clean to remove them.
WARNING:   excluded but present: manuscript/back-matter/appendix.md
WARNING:   excluded but present: config/amazon-kdp-info.md

To interactively delete them:

poetry run init-bp --clean

This will list the items and ask for confirmation before deleting anything.

---

Directory Structure After Initialization

book-project/
├── manuscript/
│   ├── chapters/
│   │   ├── 01-chapter.md
│   │   └── 02-chapter.md
│   ├── front-matter/
│   │   ├── toc.md
│   │   ├── toc-print.md
│   │   ├── preface.md
│   │   └── foreword.md
│   └── back-matter/
│       ├── about-the-author.md
│       ├── acknowledgments.md
│       ├── epilogue.md
│       └── ...
├── assets/
│   ├── covers/
│   └── figures/
├── config/
│   ├── metadata.yaml
│   ├── export-settings.yaml
│   ├── voice-settings.yaml
│   ├── init-settings.yaml
│   └── data/
│       └── image_prompt_generation_template.json
├── output/
├── pyproject.toml
├── Makefile
├── README.md
└── LICENSE

---

Re-running the Initializer

The initializer is idempotent. Running make init-bp again will:

• Create any missing directories and files
• Overwrite pyproject.toml name/description and metadata.yaml with new input
• Not delete existing files or content
• Log what was created vs. what already existed

INFO: Directory already exists: manuscript/chapters
INFO: Created directory: manuscript/exercises
INFO: File already exists: manuscript/chapters/01-chapter.md
INFO: Created file: manuscript/chapters/03-chapter.md

Done: 1 dirs created, 1 files created, 31 already existed.

This makes it safe to re-run after changing your book title or adding new structure via init-settings.yaml.

---

Makefile Targets

Target	Description
make init-bp	Initialize a new book project (runs lock-install first)
make init-project	Alias for init-bp
make setup	Install dependencies and run init-bp
make lock-install	Lock and install dependencies

See the Makefile Overview for the full list of targets.

---

Related

• Generate Project Structure - Overview of the directory layout
• Makefile Overview - All available make targets
• How to Write a Book - Conventions for chapters and metadata