Skip to content

## Implement manuscripto core: assembly, render, and notio section type Impleme

Implement manuscripto core: assembly, render, and notio section type

Implement the core manuscripto functionality: section management via notio, markdown assembly, and pandoc rendering.

Prerequisites

  • The manuscripto package has been scaffolded at packages/manuscripto/ by a prior task.
  • Read the design spec at docs/explanation/manuscripto-design-spec.md.
  • Read the schema at packages/manuscripto/src/manuscripto/schema.py (already implemented).
  • Read pixecog's Lua filter: use worklog_read_file(project_id="pixecog", path="code/utils/lua/include.lua") to understand the transclusion pattern.

Deliverables

1. Section management (section.py)

  • list_sections(root, manuscript_name) → list sections for a manuscript, ordered by order field
  • create_section(root, manuscript_name, title, order, template) → create a section markdown file
  • Integration with notio: sections are stored under docs/manuscript/<name>/sections/ with frontmatter: 
    title: Introduction
order: 2
series: manuscript-<name>
manuscript: <name>
  • Sections are plain markdown with [@citekey] citations and ![caption](figure.pdf) figures
  • Ordering uses the order integer field, not filename prefix (but filenames can have prefix for human readability)

2. Assembly (assembly.py)

  • assemble(root, manuscript_name) → read ManuscriptSpec, gather sections in order, concatenate into single markdown document
  • Insert YAML metadata block at top (title, author, date, abstract from cover section)
  • Between sections, insert \newpage or configurable separator
  • Figure references: resolve figio figure IDs to actual file paths
  • Output: write to _build/md/<name>-assembled.md
  • This replaces the dual-marker master.md pattern — the assembled file IS the Pandoc input

3. Rendering (render.py)

  • render(root, manuscript_name, format="pdf") → invoke pandoc on assembled markdown
  • Supported formats: pdf, latex, md (resolved markdown with citations), html
  • Build pandoc command from ManuscriptSpec config:
  • --bibliography=<bib_path> from biblio
  • --csl=<csl_path>
  • --pdf-engine=<engine> (default: xelatex)
  • --citeproc
  • Resource path includes figure directories
  • Use subprocess.run with the correct conda environment (respect runtime_conventions — check .projio/config.yml for projio_python or use current Python)
  • Output to _build/{format}/<name>.<ext>
  • Return structured result: success/failure, output path, warnings, pandoc stderr

4. Figure integration (figures.py)

  • extract_captions(root, figure_ids) → read figio FigureSpec files and extract caption annotations
  • insert_figure_ref(section_text, figure_id, caption, position) → insert pandoc figure reference at specified position
  • resolve_figure_paths(root, manuscript_name) → map figure IDs to built SVG/PDF paths

5. Validation (validate.py)

  • validate_manuscript(root, manuscript_name) → check:
  • All sections referenced in ManuscriptSpec exist
  • Section order has no gaps or duplicates
  • All [@citekey] references exist in the bibliography file
  • All figure references have corresponding figio specs
  • Pandoc is available in PATH
  • Return structured validation result with errors and warnings

6. CLI (cli.py)

  • manuscripto init <name> — create manuscript structure + ManuscriptSpec
  • manuscripto build <name> [--format pdf|latex|md|html] — assemble + render
  • manuscripto validate <name> — run all validation checks
  • manuscripto status <name> — show sections, figures, completeness
  • manuscripto assemble <name> — just assembly, no render (for preview)

7. Tests

  • test_assembly.py: test section ordering and concatenation
  • test_schema.py: extend with ManuscriptSpec validation tests

Notes

  • Keep it simple. The Lua filter approach from pixecog is NOT needed — manuscripto assembles by concatenation, so no transclusion engine required.
  • Pandoc is a system dependency, not a Python package. Shell out to it.
  • Don't implement MkDocs integration yet — that comes via projio's existing site tools.
  • For testing pandoc rendering, tests should skip if pandoc is not installed (pytest.importorskip equivalent for system binaries).
  • [[docs/log/task/task-arash-20260331-175356-958039.md]] — Direct prerequisite: scaffolds the manuscripto package that this task implements
  • [[docs/log/task/task-arash-20260331-175313-566067.md]] — Design spec that this task explicitly requires reading before implementation