Legacy Book Project Migration

Guide migration of pre-Codexis book projects so they work with Codexis builds. Choose Codexis-compatible (minimal changes) or full migration to the modern structure.

Canonical reference: test/support/fixtures/test_manuscript in the Codexis repo.

Modern book structure (target)

When using codexis build --source manuscript --output output, the source directory should match:

manuscript/
├── manuscript.tex              # or main.tex / book.tex
├── meta.yaml
├── config.yaml
├── content/
│   ├── front-matter/
│   ├── chapters/
│   ├── back-matter/
│   ├── bibliography/           # references.bib (single location)
│   ├── glossary/               # one .tex per term
│   ├── acronyms/               # one .tex per acronym
│   ├── images/
│   ├── figures/
│   └── tables/                 # optional
├── styles/
└── assets/
    ├── fonts/
    ├── ocr/
    └── scans/

Conventions: Main file at source root; single content/bibliography/references.bib; glossary/acronyms under content/glossary/ and content/acronyms/; meta.yaml and config.yaml at source root.

What already works (minimal migration)

• •Main TeX: Codexis finds manuscript.tex, main.tex, or book.tex, or any .tex with \documentclass and \begin{document}.
• •Metadata: meta.yaml is read from (1) source dir, (2) source/config/, (3) parent of source (project root).
• •Bibliography: LaTeX can use any path in \addbibresource{...}. For WikiJS citation linking, Codexis expects content/bibliography/references.bib.
• •Legacy layout: meta.yaml at project root, config at root or in source, existing content/ and styles/ are accepted.

Full migration checklist

Use this when the goal is to match test/support/fixtures/test_manuscript:

1. •Single source directory – Use one book root (e.g. manuscript/). Rename src/ to manuscript/ or keep name and match contents.
2. •Main LaTeX at source root – Use manuscript.tex (or main.tex / book.tex). If the project uses another name, rename it.
3. •meta.yaml and config.yaml at project root – Ensure both files exist at the repository root. Move from manuscript/meta.yaml and add a minimal config.yaml (formats, latex_options.engine, latex_options.main_file) if missing. Tooling and scripts often expect them at project root.
4. •Single bibliography – Create content/bibliography/references.bib (merge/copy from existing .bib). In main .tex: \addbibresource{content/bibliography/references.bib}; remove other \addbibresource paths.
5. •Glossary and acronyms – Move content/chapters/glossary/*.tex → content/glossary/, content/chapters/acronyms/*.tex → content/acronyms/. Update main .tex to \input{content/glossary/...} and \input{content/acronyms/...}.
6. •Back-matter as separate files – Use content/back-matter/ for appendix, list-of-figures, list-of-tables, glossary, bibliography, index, todo. Main .tex should \input or \include these.
7. •Cleanup – Update .gitignore for build artifacts (*.aux, *.bbl, html/, *-epub3/). Optionally remove or archive legacy scripts; Codexis does not use them.
8. •README at project root – Review, improve, or add a README (or README.md) in the repository root. It should describe the book, how to build it with Codexis, and point to manuscript/, meta.yaml, and config.yaml. If one exists, update any outdated paths (e.g. src/ → manuscript/) and replace legacy build instructions with codexis build --all --source manuscript --output output.

Optional migrations (consistency / full features)

• •Bibliography name/location: Align filename with \addbibresource{...} (rename .bib or change the LaTeX reference).
• •WikiJS citation linking: Add content/bibliography/references.bib (copy or symlink main .bib). Without it, WikiJS build works but citation linking is limited.
• •meta.yaml / config.yaml in manuscript/: Copy into source dir for “single manuscript folder” convention; not required for correct builds.
• •meta.yaml / config.yaml at project root: Ensure both exist at the repository root. Many tools and scripts expect them there. Copy meta.yaml from manuscript (or scripts/meta.yaml); add a minimal config.yaml with formats, latex_options.engine, and latex_options.main_file if the project has none.
• •Legacy scripts / artifacts: Add or update .gitignore; phase out old scripts in favor of codexis build and CLI.
• •README at project root: Review existing README/README.md for outdated paths and build instructions; add one if missing. Include book title, one-line description, prerequisites (Codexis, LaTeX), and the standard build command.

Build after migration

From project root:

codexis build --all --source manuscript --output output

Additional reference

• •Project-specific checklists (e.g. Grunch of Giants, elib-regular-polytopes) and detailed options: see reference.md.