Chapter File Generator

📘 Chapter File Generator

This tool helps you automatically create empty Markdown files for chapters (or scenes, parts, lessons—your choice) in your book project. It is designed to work with a typical structure like:

your-project/
├── manuscript/
│   └── chapters/
│       ├── 01-chapter.md
│       ├── 02-chapter.md
│       └── ...

The script is written in Python, designed for use with Poetry, and includes a command-line interface for convenience.

---

✨ Features

• ✅ Flexible filenames via --name-pattern (e.g. {num:02d}-scene.md, {num}-part.md)

• ✅ Autodetects the next number based on your chosen pattern

• ✅ Optional manual start via --start

• ✅ Dry-run mode to preview without writing files

• ✅ Ensures the manuscript/chapters/ directory exists

• ✅ Clean Poetry CLI integration

• ✅ Works with default or custom project root

ℹ️ The --name-pattern must include a {num} placeholder (with optional formatting like :02d).
Examples: {num:02d}-chapter.md, {num:03d}_scene.md, {num}-part.md

---

📁 Folder Structure & Script Location

By default, the script operates on this structure:

<project-root>/
├── manuscript/
│   └── chapters/

📌 Command: poetry run create-chapters
If no --project-dir is provided, files are created under:

./manuscript/chapters/

---

⚙️ Installation & Setup

1. Ensure manuscripta is installed via poetry install.

2. Register the CLI entry in pyproject.toml:

the manuscripta library
create-chapters = "scripts.create_chapters:main"

3. Run poetry install if needed.

You can now invoke it from anywhere inside your project:

poetry run create-chapters

---

🚀 Usage Examples

1) Create the next 5 items (default chapter filenames)

poetry run create-chapters --total 5

🟢 Output: Files like 03-chapter.md … 07-chapter.md (starting after the highest existing)
📁 Location: ./manuscript/chapters/

---

2) Start from a specific number

poetry run create-chapters --start 3 --total 7

🟢 Sample output:

✓ Created: .../manuscript/chapters/03-chapter.md
✓ Created: .../manuscript/chapters/04-chapter.md
...
✓ Created: .../manuscript/chapters/09-chapter.md

---

3) Use a custom project folder

poetry run create-chapters --project-dir my-book --total 3

🟢 Output: Files created inside my-book/manuscript/chapters/

---

4) Use a custom filename pattern (scenes)

poetry run create-chapters --total 3 --name-pattern "{num:02d}-scene.md"

Creates:

01-scene.md
02-scene.md
03-scene.md

---

5) Three‑digit padding with underscore (parts)

poetry run create-chapters --total 2 --start 10 --name-pattern "{num:03d}_part.md"

Creates:

010_part.md
011_part.md

---

6) Preview only (no files written)

poetry run create-chapters --total 5 --dry-run --name-pattern "{num}-lesson.md"

Shows what would be created without touching the filesystem.

---

🧠 How It Works

1. Builds the target directory: <project-root>/manuscript/chapters/ (or under --project-dir).

2. Parses your --name-pattern and converts it to a regex so it can detect existing files that match the pattern.

3. If --start is omitted, it finds the highest existing number that matches the pattern and continues from there; otherwise it uses your --start.

4. Creates empty Markdown files using your pattern (e.g., {num:02d}-chapter.md → 03-chapter.md).

🔐 Safety: Existing files are not overwritten—touch(exist_ok=True) is used.

---

💡 Common Scenarios

✅ New book project

poetry run create-chapters --total 10

Creates:

01-chapter.md … 10-chapter.md

---

✅ Extend an existing list

poetry run create-chapters --total 3

If the last file is 07-chapter.md, it adds:

08-chapter.md … 10-chapter.md

---

✅ Fill a gap manually

poetry run create-chapters --total 2 --start 20

Creates:

20-chapter.md
21-chapter.md

---

❗ Notes & Tips

• The pattern must contain {num} (optionally formatted like {num:02d}).

• To include a literal brace in your pattern, double it (e.g., {{ or }}) due to str.format rules.

• Non-matching files in the folder are ignored during autodetection.

• Use --dry-run to validate your pattern and the planned filenames before creation.

---

🧪 Tests (optional)

A pytest suite covers:

• default vs. custom project dirs

• autodetection of the next number based on your pattern

• explicit --start behavior

• dry-run behavior

• pattern validation (missing {num} raises an error)

---

📜 License

The script is open for reuse and adaptation under your project’s license.

---