# Publisher DOCX Skill

> Converts bidirectionally between DOCX/PDF and Markdown, edits existing DOCX files programmatically, or prepares a journal-ready manuscript. TRIGGER when: user needs DOCX↔Markdown conversion, wants to create a styled Word document from Markdown, needs to batch-edit/modify an existing DOCX file, or wants to produce a publisher-styled manuscript (e.g. Elsevier, ACS, IEEE, Nature, or a Korean generic profile). DO NOT TRIGGER when: user only needs to convert non-DOCX formats (images, HTML, etc.) to Markdown — use markitdown instead.

- Skill: `wjgoarxiv/publisher-docx-skill` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add wjgoarxiv/publisher-docx-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wjgoarxiv/publisher-docx-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: wjgoarxiv (https://skillmd.com/u/wjgoarxiv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wjgoarxiv/publisher-docx-skill

---


# Document Conversion & Editing Toolkit

This skill provides **bidirectional conversion** between DOCX/PDF and Markdown, plus DOCX editing capabilities:

- **DOCX/PDF → Markdown**: Convert documents to clean, reader-friendly Markdown
- **Markdown → DOCX**: Create properly-styled Word documents from Markdown
- **DOCX Editing**: Modify existing DOCX files (find/replace, append, insert)

> [!IMPORTANT]
> **Deep-interview intake comes first.** When this skill is used, do not begin
> conversion, editing, linting, or template selection until you first ask the
> user one concise, deep-interview-style ambiguity-reduction question. The
> question must clarify: (1) the intended document purpose/audience, (2) desired
> output files (`.docx`, `.pdf`, Markdown, lint report, edited DOCX), (3) styling
> target or preset (`elsevier`, `acs`, `ieee`, `nature`, `korean-generic`,
> `ko-executive-report-*`, custom), (4) source file location and where outputs
> should be saved, and (5) hard constraints such as language/locale, journal or
> executive-report tone, deadline, font/color preferences, and what must stay out
> of scope.
>
> Suggested first question:
>
> "Before I touch the files, what is the document's purpose/audience, which
> output files do you want, which style or preset should it follow, where are the
> source/output paths, and are there any hard constraints on language, fonts,
> colors, publisher/report tone, deadline, or out-of-scope changes?"
>
> If the user has already provided all of that information explicitly, restate
> the resolved brief in one sentence and proceed. If the user explicitly says to
> skip clarification, proceed but note the assumed preset/output choices before
> running commands.

> [!IMPORTANT]
> If the user asks for an **Elsevier / ACS / IEEE / Nature / korean-generic /
> ko-executive-report** manuscript or report,
> do **not** start with the basic Markdown→DOCX path.
> Start with:
>
> ```bash
> python scripts/convert_md_to_docx.py draft.md out.docx --publisher <profile>
> python scripts/slop_lint.py draft.md --publisher <profile> --report report.md
> ```
>
> Use the plain `convert_md_to_docx.py input.md output.docx` command only when
> no publisher-specific workflow is requested.

> [!CAUTION] > **Do not write your manuscript files into this skill folder.**
> Your input `.md` and output `.docx`/`.pdf` files belong in your working directory.
> Run scripts using absolute paths to this skill folder, e.g.:
>
> ```bash
> python /path/to/publisher-docx-skill/scripts/convert_md_to_docx.py ./input.md ./output.docx
> ```
>
> The `templates/`, `references/`, and `scripts/` subdirectories inside this skill
> are intentionally extensible and are maintained by the skill author. Running
> `scripts/generate_docx_templates.py` regenerates `templates/docx/*.docx` from
> `templates/registry.yaml`; this is the supported way to update publisher styles.

## When to Use

- Need production-grade Markdown from DOCX or PDF for docs, LLM context, or web publishing.
- Want to create DOCX documents from Markdown with proper styling.
- Need to edit existing DOCX files programmatically (batch replacements, content insertion).
- Documents include tables, images, footnotes, math, or tracked changes.
- Preparing a publisher-styled manuscript from Markdown? **Prefer** `convert_md_to_docx.py --publisher ...` over the plain legacy Markdown→DOCX path.
- Want a non-destructive manuscript quality check before submission? Run `scripts/slop_lint.py` after the publisher DOCX workflow.

## Recommended workflow for submissions

If the user asks for a journal-ready manuscript, use this order:

1. `python scripts/convert_md_to_docx.py draft.md out.docx --publisher <profile>`
2. `python scripts/slop_lint.py draft.md --publisher <profile> --report report.md`
3. Optional TeX-enabled path: `python scripts/convert_md_to_pdf.py draft.md out.pdf --publisher <profile>`

Use the plain `convert_md_to_docx.py input.md output.docx` flow only when no publisher-specific styling is requested.

## Prerequisites

- **Core**: python3
- **DOCX → MD**: pandoc
- **PDF → MD**: pymupdf (`pip install pymupdf`)
- **MD → DOCX**: python-docx, markdown, beautifulsoup4 (`pip install python-docx markdown beautifulsoup4`)

---

## DOCX → Markdown Workflow

1. Convert with pandoc (stable tables, extracted media):

```bash
pandoc "input.docx" \
  -f docx -t gfm \
  --wrap=none \
  --extract-media="media" \
  --reference-links \
  --markdown-headings=atx \
  --output "draft.md"
```

- Tracked changes: add `--track-changes=all` (or accept/reject first).
- If table lines wrap, add `--columns=200` and re-run.

2. Clean the Markdown:

```bash
python scripts/clean_markdown.py draft.md output.md
```

3. Review with the checklist: `references/markdown_quality_checklist.md`

4. (Optional) Inline images for self-contained MD:

```bash
python scripts/embed_images.py output.md output.inline.md --root media
```

---

## PDF → Markdown Workflow

```bash
pip install pymupdf  # if not installed
python scripts/convert_pdf.py input.pdf output.md
```

This handles multi-column layouts, paragraph merging, and header/footer removal.

---

## Journal Manuscript Workflow (NEW)

Generate a publisher-styled manuscript directly from a Markdown draft using the
`--publisher` flag. The skill ships a data-driven style registry at
`templates/registry.yaml` and a generated DOCX template at
`templates/docx/<publisher>.docx`. Supported publisher profiles are
`elsevier`, `acs`, `ieee`, `nature`, `korean-generic`,
`ko-executive-report-core`, `ko-executive-report-navy`, and
`ko-executive-report-forest`.

```bash
python scripts/convert_md_to_docx.py input.md output.docx --publisher elsevier
python scripts/convert_md_to_docx.py input.md output.docx --publisher acs
python scripts/convert_md_to_docx.py input.md output.docx --publisher ieee
python scripts/convert_md_to_docx.py input.md output.docx --publisher nature
python scripts/convert_md_to_docx.py input.md output.docx --publisher korean-generic
python scripts/convert_md_to_docx.py input.md output.docx --publisher ko-executive-report-core
python scripts/convert_md_to_docx.py input.md output.docx --publisher ko-executive-report-navy
python scripts/convert_md_to_docx.py input.md output.docx --publisher ko-executive-report-forest
```

### YAML frontmatter contract

Put a YAML block at the top of your Markdown. The converter uses it to build
the title/author/affiliation/abstract/keyword block per the publisher's
`design.title_block` rules.

```yaml
---
title: "Catalytic CO2 reduction on Cu/ZnO: a mechanistic study"
authors:
  - { name: "Woojin Go", affiliation: 1, corresponding: true }
  - { name: "Jane Doe",  affiliation: [1, 2] }
affiliations:
  1: "Department of Chemical Engineering, University X"
  2: "Advanced Materials Institute, University Y"
abstract: "We report ..."
keywords: [CO2 reduction, Cu/ZnO, DFT, operando XPS]
corresponding_email: "wj@example.ac.kr"
---
```

---

## Markdown → DOCX Workflow (Basic / non-publisher)

Use this path only when the user does **not** need publisher-specific styling.

```bash
python scripts/convert_md_to_docx.py input.md output.docx
```

**Features:**

- Headings (H1-H6 → Word heading styles)
- Bold, italic, inline code formatting
- Bullet and numbered lists
- Tables with proper styling
- Code blocks (monospace font)
- Links (as hyperlinks)
- Local images

**With template:**

```bash
python scripts/convert_md_to_docx.py input.md output.docx --template template.docx
```

### What `--publisher` does automatically

When `--publisher` is set, the following anti-slop filters run on your text
before and after conversion:

- **Micro-typography**: straight `"..."` → curly `"..."`, `10-15 mg` →
  `10–15 mg` (en-dash + non-breaking space), `word - word` → `word — word`,
  `...` → `…`, `Fig. 1` / `Table 1` / `Eq. 1` → with non-breaking space.
- **Heading auto-numbering**: `Heading 1` → `1.`, `Heading 2` → `1.1.`, etc.
- **Booktabs tables**: python-docx's `Table Grid` (vertical rules) is replaced
  with top/header-bottom/bottom horizontal rules only.
- **Title block injection** from YAML frontmatter (superscript affiliations,
  corresponding-author marker, abstract label, keywords line).
- **CJK font pairing**: every run gets `w:eastAsia=Pretendard` so Hangul in
  the source renders as Pretendard rather than the default system CJK font.
- **Banned-font / banned-style stripping**: Calibri, Cambria, Aptos, Table
  Grid, Intense Quote, List Paragraph, Subtle Emphasis are removed if they
  leak in.
- Fenced code blocks and inline backtick code are preserved byte-for-byte.

### Locale auto-detection

```bash
python scripts/convert_md_to_docx.py input.md output.docx --publisher elsevier --locale auto
```

`--locale` defaults to `auto` and detects Korean via Hangul codepoint ratio
(>5% → `ko`, 1–5% → `mixed`, else `en`). The Korean-specific lint rules are
scheduled for M6 of the journal enhancement work. The
`korean-generic` profile is available now for mixed KR/EN manuscripts that
need explicit Pretendard-first typography.

### Regenerating templates

After editing `templates/registry.yaml`, rebuild the generated `.docx` files:

```bash
python scripts/generate_docx_templates.py                   # all publishers
python scripts/generate_docx_templates.py --publisher elsevier
python scripts/generate_docx_templates.py --publisher acs
python scripts/generate_docx_templates.py --publisher ieee
python scripts/generate_docx_templates.py --publisher nature
python scripts/generate_docx_templates.py --publisher korean-generic
python scripts/generate_docx_templates.py --publisher ko-executive-report-core
python scripts/generate_docx_templates.py --publisher ko-executive-report-navy
python scripts/generate_docx_templates.py --publisher ko-executive-report-forest
```

Adding a new publisher is a data-only change: copy an existing block in
`templates/registry.yaml`, edit the values per the publisher's author guide,
and rerun the generator.

### LaTeX / PDF path

Generate a submission-style PDF via pandoc + XeLaTeX:

```bash
python scripts/convert_md_to_pdf.py input.md output.pdf --publisher elsevier
python scripts/convert_md_to_pdf.py input.md output.pdf --publisher korean-generic
```

This path uses publisher-specific templates under `templates/latex/<publisher>/`
and checks for the required TeX Live class before compilation. If `xelatex`,
`kpsewhich`, or the required class is missing, the script exits non-zero with a
clear install hint instead of failing halfway through compilation.

### Anti-slop lint

Run a non-destructive prose lint pass before submission:

```bash
python scripts/slop_lint.py input.md --publisher elsevier --report report.md
python scripts/slop_lint.py input.md --publisher nature --report report.md --fix-whitespace
```

Current rule coverage includes banned AI-tell phrases, hedging pileups, stock
openers/closers, citation-density heuristics, section-order checks, heading-case
checks, qualifier/adjective-stack warnings, and a safe whitespace/typography
autofix mode that writes a `.fixed.md` sibling.

### Publisher Registry

The publisher registry lives in `templates/registry.yaml`.

- Edit the YAML to add or refine a publisher profile.
- Regenerate `.docx` templates with `scripts/generate_docx_templates.py`.
- The DOCX, lint, and optional PDF paths all consume the same registry.
- This keeps publisher support data-driven rather than hard-coded.

---

## Edit Existing DOCX (NEW)

Modify existing DOCX files with common operations:

### Find & Replace

```bash
python scripts/edit_docx.py input.docx --replace "OLD_TEXT" "NEW_TEXT" -o output.docx
```

Add `--case-insensitive` for case-insensitive matching.

### Append Markdown Content

```bash
python scripts/edit_docx.py input.docx --append-md extra_content.md -o output.docx
```

### Insert at Placeholder

```bash
python scripts/edit_docx.py input.docx --insert-at "{{MARKER}}" "Replacement text" -o output.docx
```

### Extract Text

```bash
python scripts/edit_docx.py input.docx --extract-text
```

### Show Document Structure

```bash
python scripts/edit_docx.py input.docx --show-structure
```

---

## Quality Checklist

- Headings: correct hierarchy, single blank line before, none empty.
- Tables: blank line before/after; merged cells rewritten if needed.
- Lists: consistent indentation; avoid hard wraps mid-bullet.
- Images: relative to media/; add alt text; widths removed.
- Math/footnotes: render and resolve; definitions present.
- Spacing: no trailing spaces; ≤2 consecutive blank lines.

---

## References

| Script                                     | Purpose                          |
| ------------------------------------------ | -------------------------------- |
| `scripts/clean_markdown.py`                | Post-conversion Markdown cleanup |
| `scripts/convert_pdf.py`                   | PDF → Markdown conversion        |
| `scripts/embed_images.py`                  | Inline images as base64          |
| `scripts/convert_md_to_docx.py`            | **Markdown → DOCX**              |
| `scripts/convert_md_to_pdf.py`             | **Markdown → PDF (optional)**    |
| `scripts/slop_lint.py`                     | **Anti-slop prose lint**         |
| `scripts/visual_audit.py`                  | **Visual audit render smoke**    |
| `scripts/edit_docx.py`                     | **Edit existing DOCX**           |
| `references/markdown_quality_checklist.md` | Quality review guide             |
| `references/journal_style_spec.md`         | Cross-publisher style matrix     |
| `references/frontmatter_schema.md`         | YAML frontmatter contract        |
| `references/slop_rules.md`                 | Lint rule definitions            |
| `references/frontmatter_schema.md`         | YAML frontmatter contract        |
| `references/slop_rules.md`                 | Lint rule explanations           |