law-review-docx

Law Review DOCX Export

Convert markdown drafts into a properly formatted Word document using the law review template via pandoc.

Usage

uv run python3 ${CLAUDE_SKILL_DIR}/scripts/build_docx.py PROJECT_DIR [--output PATH] [--fix-footnotes]

The script:

1. Detects title/author from .planning/ACTIVE_WORKFLOW.md or PRECIS.md
2. Combines all drafts/*Draft*.md files in section order (Introduction → Parts → Conclusion → Appendix)
3. Strips YAML frontmatter and prefixes footnote labels to avoid cross-section collisions
4. Resolves <!-- include: PATH --> sentinels by inlining file contents (paths must be absolute or ~-expanded)
5. Runs pandoc with --reference-doc pointing to the law review template
6. Optionally runs the docx-footnotes repair script (--fix-footnotes)

Compile-Time Includes

To embed externally generated tables or fragments at build time, place a sentinel in the draft:

<!-- include: ~/projects/mirror/data/tables/paper/table2_body.md -->

The preprocessor expands ~, reads the file, and splices its contents inline before pandoc runs. Missing or non-absolute paths emit a visible <!-- MISSING: ... --> placeholder instead of failing silently. For images, use plain pandoc markdown (![caption](~/path/to/figure.png)) — no sentinel needed.

Detecting the Project Directory

If the user doesn't specify a path, detect it from context:

1. Check if current working directory has drafts/ and .planning/
2. Check if .planning/ACTIVE_WORKFLOW.md exists and read project_dir from it
3. Follow symlinks (e.g., paper → actual project directory)

Template

The reference template lives at:

${CLAUDE_SKILL_DIR}/../writing-legal/templates/law_review_template.docx

This template defines all styles that pandoc applies:

Style	Use	Formatting
Title	Article title	Bold, small caps, centered
Heading 1	Part titles (I., II., III.)	Bold, left-aligned
Heading 2	Sections (A., B., C.)	Bold, left-aligned
Heading 3	Subsections (1., 2., 3.)	Italic, left-aligned
Body Text	All body paragraphs	First-line indent
First Paragraph	After headings	No indent
Footnote Text	Footnotes	10pt, single-spaced

After Export

Report the output path, section count, footnote count, and approximate word count. If the user needs further formatting (NOTEREF cross-references, footnote repair from cloud editing), suggest --fix-footnotes or the docx-footnotes skill.

Known Gotcha: Pandoc-Citeproc Paren-Wrap Inside Footnotes

Symptom. In the compiled DOCX, some footnotes read with a doubled space and wrapping parens around a citation:

see  (Griffin, supra note 12; Macey, supra note 12). For proponents...

(note the two spaces before ().

Root cause. Pandoc-citeproc wraps any bracketed parenthetical citation [@key] or [signal @key] in parens with a leading space when it appears mid-paragraph inside a footnote body. At the paragraph start the wrap is suppressed; mid-paragraph it is not. This is native pandoc behavior for note-style CSLs and cannot be fixed at the CSL level.

Why the natural-looking fix doesn't work. Rewriting source to bare textual form (@key without brackets) renders cleanly only if every citation has a locator. For bib entries without locators (books, misc, many articles), pandoc-citeproc with a note-style CSL emits just a stray number (1.) because the full cite is supposed to go into a footnote and there is no footnote to host it (we're already inside one).

Fix. The docx-footnotes skill's fix_footnotes.py detects and strips these wraps post-compile. The detector keys on the distinctive XML signature:

<w:r><w:t xml:space="preserve"> </w:t></w:r>     <!-- natural space -->
<w:r><w:t xml:space="preserve"> </w:t></w:r>     <!-- EXTRA space -->
<w:r>…<w:t>(Author,</w:t></w:r>                  <!-- open paren run -->
… citation content …
<w:r>…<w:t>)</w:t></w:r>                         <!-- close paren (standalone or attached) -->

Author-written explanatory parentheticals ((describing X), (documenting Y)) appear as a single <w:t> (…)</w:t> run and lack the double-whitespace signature, so they are preserved. build_docx.py runs fix_footnotes.py automatically when --fix-footnotes is set (the default).

Red Flags

Action	Why Wrong	Do Instead
Running pandoc -o output.docx without --reference-doc	Produces default Calibri formatting that violates journal requirements	Always use the template
Manually constructing the DOCX with python-docx or docx-js	Reinvents what the template + pandoc already handle	Run the script
Combining markdown without prefixing footnote labels	Causes footnote collisions when multiple sections use [^1]	The script handles this automatically