anthropics / anthropics/claude-code

docx skill: docx-js output has no default "Normal" paragraph style, breaks python-docx readers

Đang mở Phù hợp với người mới
#91,025 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
area:skills bug platform:windows
Ngôn ngữ chính
Python
Star
145k
Fork
23.1k
Chỉ số merge pull request
Chỉ số pull request đang chờ

Mô tả

## Summary

When the `docx` skill generates a `.docx` via its docx-js code path (`docx` npm package, observed v9.7.1) without an explicit `styles` option, the resulting `styles.xml` has no "Normal" paragraph style at all — and no paragraph style is marked as the document default. Any tool built on `python-docx` that reads `paragraph.style.name` on an unstyled paragraph then crashes with `AttributeError: 'NoneType' object has no attribute 'name'`, because `python-docx`'s `Styles.default(WD_STYLE_TYPE.PARAGRAPH)` returns `None` when nothing is marked default — it does not fall back to Word's own `w:docDefaults` behavior.

## Reproduction

```js
const { Document, Paragraph, TextRun, Packer } = require("docx"); // v9.7.1
const doc = new Document({
sections: [{ children: [new Paragraph({ children: [new TextRun("hello")] })] }],
});
Packer.toBuffer(doc).then(buf => require("fs").writeFileSync("out.docx", buf));
```

Inspecting `out.docx`'s `word/styles.xml` shows only `Title, Heading1-6, Strong, ListParagraph, Hyperlink, FootnoteReference, FootnoteText, FootnoteTextChar, EndnoteReference, EndnoteText, EndnoteTextChar` — no `Normal`, and nothing marked `w:default="1"` for a paragraph-type style. `DefaultStylesFactory.newInstance()` in this version of `docx` simply never emits one.

```python
from docx import Document
d = Document("out.docx")
p = d.paragraphs[0]
p.style # None
p.style.name # AttributeError: 'NoneType' object has no attribute 'name'
```

## Fix that works

Pass an explicit `styles.paragraphStyles` entry for `"Normal"` in the `Document` constructor, and set `style: "Normal"` on every `Paragraph` that isn't a heading/bullet (including paragraphs used as table-cell content or as empty spacers):

```js
const doc = new Document({
styles: {
paragraphStyles: [{
id: "Normal", name: "Normal", quickFormat: true,
run: { font: "Calibri", size: 22 },
paragraph: { spacing: { line: 276 } },
}],
},
sections: [{ children: [new Paragraph({ style: "Normal", children: [new TextRun("hello")] })] }],
});
```

With every paragraph carrying an explicit `w:pStyle`, `python-docx` resolves `paragraph.style.name` correctly ("Normal").

## Ask

Document this in the `docx` skill's SKILL.md "Creating with docx-js" gotchas (or fix `DefaultStylesFactory` upstream in the vendored `docx` package to always emit a default Normal style, matching what python-docx/Word themselves guarantee). This affects any downstream tooling built on `python-docx` that touches `paragraph.style` on docx-js output — not just a cosmetic styling gap.

## Environment

- `docx` npm package v9.7.1, resolved via the `docx` skill's own scratchpad `node_modules`
- `python-docx` (current PyPI release as of 2026-08)
- Windows 11, Claude Code CLI

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Hướng nghiên cứu

Find the docx skill's SKILL.md and its "Creating with docx-js" gotchas section mentioned in the issue. Read the reproduction and working fix, then add a note that docx-js output needs an explicit Normal paragraph style and explicit style on normal paragraphs for python-docx readers. Done means the gotcha is documented clearly with the affected versions/tools named.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
javascript, node.js, python
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
82/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.