nightshift/utils/textdoc-compile/README.md

Textdoc Compiler

NightShift Story Compiler

Compile structured markdown fiction projects into novel-style builds.

Generates:

• paperback-style PDF
• assembled markdown manuscript
• HTML preview
• optional cover support
• front matter
• act divider pages
• table of contents

Designed for AI-assisted longform fiction pipelines.

---

Features

• Pure Python

• Windows-friendly

• Natural scene sorting:

  • scene-003.md
  • scene-003a.md
  • scene-003b.md

• Front matter support via chapter-000

• Act dividers parsed from .nightshift/tasks.md

• Multiple chapter naming styles

• Optional metadata/title pages

• Paperback or manuscript formatting

• Scene heading extraction

• TOC generation

• Clean build output folder

---

Example Project Structure

project-root/
│
├── compile_story.py
│
├── .nightshift/
│   └── tasks.md
│
└── story/
    ├── TITLE.md
    ├── metadata.json
    ├── cover.png
    │
    ├── chapters/
    │   ├── chapter-000/
    │   │   ├── scene-001.md
    │   │   └── scene-002.md
    │   │
    │   ├── chapter-001/
    │   │   ├── scene-001.md
    │   │   ├── scene-002.md
    │   │   └── scene-003a.md
    │   │
    │   ├── chapter-002/
    │   └── chapter-003/
    │
    └── build/

---

Install

pip install markdown reportlab

---

Quick Start

python compile.py --root .

Outputs:

story/build/
  manuscript.md
  manuscript.html
  manuscript.pdf

---

Title Pages

TITLE.md

If present:

story/TITLE.md

Its contents are inserted as the title page.

Example:

# NightShift

## A Novel

KHodges42

---

metadata.json

Optional metadata fallback if TITLE.md is missing.

Example:

{
  "title": "NightShift",
  "subtitle": "A Novel",
  "author": "KHodges42",
  "language": "en"
}

---

Cover Support

Optional:

story/cover.png

Currently:

• included in markdown/html
• copied into build folder
• ignored in ReportLab PDF for now

Future versions can embed directly into PDF.

---

Front Matter

chapter-000 is treated specially.

Example:

story/chapters/chapter-000/

Use for:

• foreword
• acknowledgements
• author notes
• epigraphs
• dedication

No chapter numbering is applied.

---

Act Dividers

Acts are parsed from:

.nightshift/tasks.md

Example:

# ACT 1 - LOW HEAT
# ACT 2 - STATIC BODIES
# ACT 3 - RECURSIVE CONTAMINATION

Each act becomes a standalone divider page.

Only the ACT headings are parsed.

Everything else in tasks.md is ignored.

---

Chapter Naming

Default:

--chapter-format folder

Results in:

chapter-001
chapter-002

Other options:

--chapter-format number

001
002

--chapter-format word

Chapter 1
Chapter 2

--chapter-format chapter-dash

Chapter-001
Chapter-002

--chapter-format none

No chapter headings.

---

Table of Contents

Default:

--toc full

Options:

Full

--toc full

Chapters + scenes.

Chapters Only

--toc chapters

Compact Acts

--toc acts

Disable

--toc off

---

PDF Styles

Paperback (default)

--pdf-style paperback

• compact trim size
• tighter margins
• novel-like formatting

Manuscript

--pdf-style manuscript

• wider margins
• larger spacing
• draft/review friendly

---

Scene Headings

By default:

• first # Heading in each scene file becomes scene title
• heading is normalized into manuscript structure

Disable:

--no-scene-headings

---

Example Commands

Default Build

python compile_story.py --root .

Paperback Build

python compile_story.py --root . --pdf-style paperback

Manuscript Draft

python compile_story.py --root . --pdf-style manuscript

No TOC

python compile_story.py --root . --toc off

Word Chapter Format

python compile_story.py --root . --chapter-format word

---

Notes

Natural Sorting

Scene files are sorted naturally.

Example:

scene-001.md
scene-002.md
scene-003.md
scene-003a.md
scene-003b.md
scene-004.md

---

EPUB

Not currently implemented.

Can be added later using:

• ebooklib
• pandoc
• markdown-it-py pipelines

---

Planned Features

• EPUB export
• embedded cover art in PDF
• page numbers
• running headers
• chapter drop caps
• better typography
• custom fonts
• widow/orphan control
• scene separators
• theme presets
• print-ready trim sizes
• LaTeX backend
• AI-generated glossary/index support

---

License

GPL3v2