Restructure Chapters

📖 Reorder & Rename Chapters Script

Overview

The reorder_and_rename_chapters.py script provides a safe and automated way to reorder and rename chapter files in the manuscript and normalize their H1 headers and anchor IDs.

It is especially useful when chapters have been restructured (e.g. Spanish, English, German editions of The Currency of the Mind) and you need to align file names and anchors consistently.

---

✨ Features

• Two-phase renaming
  Renames files safely via a temporary .tmpmove extension to avoid filename collisions.

• H1 header normalization
  Updates the top header line, e.g.

  # ✦ Capítulo 7: Creatividad – La moneda renovable {#-chapter-7}
  

  ensuring that the number and anchor ID always match the filename.

• Anchor ID synchronization
  Ensures {#-chapter-N} is consistent with the file’s chapter number.

• Language support
  Recognizes and normalizes headers for Spanish (Capítulo), German (Kapitel), and English (Chapter).
  You can force a language via --lang, or let the script auto-detect.

• Mapping flexibility
  Chapter mappings can be:

  • Provided inline via --map src:tgt

  • Loaded from a file (.json, .csv, .yaml)

• Dry run mode
  Preview all operations without changing any files.

• Poetry integration
  Configured as a Poetry script for simple CLI usage.

---

⚙️ Installation

Make sure your project is Poetry-based and manuscripta is installed.

In pyproject.toml add:

the manuscripta library
reorder-chapters = "scripts.reorder_and_rename_chapters:main"

Reinstall or update your Poetry environment:

poetry install

Now the command poetry run reorder-chapters is available.

---

🚀 Usage

1. Dry Run (recommended first)

poetry run reorder-chapters --dry-run \
  --base-dir manuscript/chapters \
  --map-file mapping.json --lang es

2. Apply Changes

poetry run reorder-chapters --base-dir manuscript/chapters --map-file mapping.json --lang es

3. Inline Mapping

poetry run reorder-chapters --base-dir manuscript/chapters \
  --map 11-chapter.md:07-chapter.md \
  --map 14-chapter.md:08-chapter.md \
  --map 16-chapter.md:09-chapter.md \
  --lang es

---

📂 Mapping File Formats

JSON

{
  "11-chapter.md": "07-chapter.md",
  "14-chapter.md": "08-chapter.md",
  "16-chapter.md": "09-chapter.md"
}

CSV

src,tgt
11-chapter.md,07-chapter.md
14-chapter.md,08-chapter.md
16-chapter.md,09-chapter.md

YAML

- src: "11-chapter.md"
  tgt: "07-chapter.md"
- src: "14-chapter.md"
  tgt: "08-chapter.md"
- src: "16-chapter.md"
  tgt: "09-chapter.md"

YAML requires pyyaml. Install with:
poetry add pyyaml

---

📝 Options

Option	Description
--base-dir PATH	Base directory of chapter files (default: manuscript/chapters)
--map-file FILE	Mapping file (.json, .csv, .yaml)
--map src:tgt	Inline mapping, can be repeated
--lang {es,de,en}	Force language for H1 normalization (auto-detect if omitted)
--dry-run	Preview changes without modifying files

---

🔒 Safety & Error Handling

• Two-phase renaming prevents accidental overwriting.

• Warns if source files are missing.

• Errors out if mapping contains duplicate targets.

• Logs every action ([OK], [WARN], [DRY]).

---

💡 Best Practices

• Always run with --dry-run first to verify.

• Commit your repo before running, so you can easily revert if needed.

• Keep your mapping files (mapping.json) in version control for traceability.

• Use separate branches per language edition (develop-es, develop-en, …).

---

📌 Example Workflow (Spanish Edition)

1. Prepare a mapping.json with the chapter renames.

2. Run a dry run:

   poetry run reorder-chapters --dry-run --map-file mapping.json --lang es

3. If the preview looks good, apply:

   poetry run reorder-chapters --map-file mapping.json --lang es

4. Check git diff and commit the changes:

   git add manuscript/chapters
   git commit -m "chore(es): reorder and rename chapters; normalize headers and anchors"

---