anthropics / anthropics/claude-code
docx skill: docx-js output has no default "Normal" paragraph style, breaks python-docx readers
- 主要语言
- Python
- 星标
- 145k
- 派生
- 23.1k
- PR 合并指标
- PR 指标待抓取
描述
## 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
贡献指南
这个仓库没有索引到贡献指南
调研方向
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.
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- javascript, node.js, python
- 领域
- documentation
- Issue 类型
- 文档
- 难度
- 2/5
- 预计耗时
- 1-3 小时
- 活跃度
- 活跃
- 描述清晰度
- 描述清楚
- 新手友好度
- 82/100