Insert, format, and cross-reference academic citations in Word documents.
Supports Chinese (GB/T 7714-2015) and international (IEEE, APA 7th, Chicago, MLA, Harvard) standards.

• Format detection - Auto-detects citation style from existing references
• Multi-format support - GB/T 7714-2015 (Chinese), IEEE, APA 7th, Chicago, MLA, Harvard
• DOI auto-fetch - Generate formatted references from DOI via CrossRef API
• BibTeX import/export - Convert between .docx references and .bib files
• Interactive console - Interactive CLI mode for quick operations
• Cross-reference hyperlinks - All [N] citations become clickable links to bibliography
• Validation - Checks orphan/missing refs, sequential ordering, recency, duplicates
• Full pipeline - One command to analyze, reformat, reorder, hyperlink, and validate
• Safe - Automatic backup before any modification

# Clone the repository
git clone https://github.com/linfewngfeng/academic-ref-inserter.git
cd academic-ref-inserter

# Install dependencies
pip install python-docx

# One command to do everything
python scripts/insert_refs.py fix --input paper.docx --format gbt7714

# 1. Analyze current state
python scripts/insert_refs.py analyze --input paper.docx

# 2. Reformat to target style
python scripts/insert_refs.py reformat --input paper.docx --format ieee

# 3. Reorder references to match citation order
python scripts/insert_refs.py reorder --input paper.docx

# 4. Add cross-reference hyperlinks (Ctrl+Click to jump)
python scripts/insert_refs.py hyperlink --input paper.docx

# 5. Validate
python scripts/insert_refs.py validate --input paper.docx --format gbt7714

# Chinese national standard
python scripts/insert_refs.py fix --input paper.docx --format gbt7714

# IEEE (engineering / CS)
python scripts/insert_refs.py fix --input paper.docx --format ieee

# APA 7th (social sciences)
python scripts/insert_refs.py fix --input paper.docx --format apa7

Before (raw docx with unformatted citations):

PM2.5 has been studied extensively [4]. Recent work [1][2] shows...

After (GB/T 7714 formatted with hyperlinks):

PM2.5 has been studied extensively [4]. Recent work [1][2] shows...

References:
[1] Wang Y, Wu H, Dong J, et al. TimeXer: Empowering transformers...[J]. NeurIPS, 2024.
[2] Liu Y, Hu T, Zhang H, et al. iTransformer: Inverted transformers...[J]. arXiv, 2023.
...

Each [N] in the text becomes a superscript black hyperlink that jumps to the bibliography entry (Ctrl+Click in Word).

academic-ref-inserter/
├── SKILL.md                    # AI assistant skill definition (Trae)
├── .cursorrules                # Cursor project rules
├── .cursor/rules/*.mdc         # Cursor 0.45+ rules
├── CLAUDE.md                   # Claude Code config
├── .github/copilot-instructions.md # GitHub Copilot config
├── .windsurfrules              # Windsurf config
├── CONVENTIONS.md              # Aider config
├── .continue/config.json       # Continue.dev config
├── AGENTS.md                   # Unified AI compatibility guide
├── opencode.json                # OpenCode config
├── GEMINI.md                     # Gemini CLI config
├── AMAZON_Q.md                   # Amazon Q Developer config
├── .clinerules                   # Cline rules
├── .kimi/skills/*/SKILL.md     # Kimi Code CLI skill
├── .qwen/skills/*/SKILL.md     # Qwen Code skill
├── README.md                   # This file
├── pyproject.toml               # Python packaging config
├── requirements.txt             # Runtime dependencies
├── requirements-dev.txt         # Dev dependencies
├── LICENSE                     # MIT License
├── scripts/
│   ├── insert_refs.py          # Main CLI entry point
│   ├── formats/
│   │   ├── base.py             # Abstract base format class
│   │   ├── gbt7714.py          # GB/T 7714-2015 implementation
│   │   ├── ieee.py             # IEEE implementation
│   │   ├── apa7.py             # APA 7th implementation
│   │   ├── chicago.py          # Chicago 17th implementation
│   │   ├── mla.py              # MLA 9th implementation
│   │   └── harvard.py          # Harvard implementation
│   └── utils/
│       ├── docx_utils.py       # Word document manipulation
│       ├── parser.py           # Reference parser
│       ├── validator.py        # Reference validator
│       ├── doi_lookup.py       # CrossRef DOI/title lookup
│       └── bibtex.py           # BibTeX import/export
├── examples/                   # Usage examples
└── tests/                      # Test suite
    ├── test_formats.py
    ├── test_validator.py
    ├── test_bibtex.py
    └── test_new_formats.py

After running, the tool verifies:

• All citations in text have matching bibliography entries
• All bibliography entries are cited in text
• Sequential numbering has no gaps/duplicates
• At least 15 references (journal paper minimum)
• At least 50% from last 5 years
• Each entry has proper type tag [J]/[M]/[C]/[D]
• Author names formatted correctly for target style
• Cross-reference hyperlinks work

cd tests
python test_formats.py

This project supports all major AI coding assistants with automatic configuration detection:

All CLI commands support --json for structured JSON output that AI agents can parse reliably.

See AGENTS.md for detailed compatibility information.

Contributions are welcome! Areas for improvement:

• Add more citation formats (Chicago, Harvard, Vancouver)
• Support for .bib / LaTeX interop
• Support for .tex files
• GUI / web interface
• More reference validation rules

MIT License - see LICENSE for details.

If you use this tool in your research, please cite:

@software{academic_ref_inserter_2026,
  author = {Academic Ref Inserter Contributors},
  title = {Academic Reference Inserter},
  year = {2026},
  url = {https://github.com/linfewngfeng/academic-ref-inserter}
}

New features — Academic Formula Inserter (实验性):

• build_docx_raw.py — 全新 OMML 公式文档生成器。在 ZIP 层直接构建 .docx，完全绕过 python-docx 的 OMML 损坏问题。支持 LaTeX → OMML 转换、MTDisplayEquation 段落样式、SEQ MTEqn 公式编号。
• convert_omml_to_mathtype.py — COM 自动化转换脚本。通过 Word COM API（SendKeys Alt+\、MTCommand、剪贴板）将 OMML 公式批量转为 MathType OLE 对象。支持 --check 检测 MathType 安装状态。
• convert_omml_to_mathtype.vbs — VBScript 版本的 COM 转换器。无需 pywin32，在桌面双击即可运行。自动逐个选中 OMML 公式并发送 MathType 转换快捷键。
• build_ole_docx.py — MathType OLE 容器构建器（实验性）。手动构造 CFB/OLE2 复合文档 + MTEF 二进制数据，生成 Equation.DSMT4 OLE 对象。注意：由于 "Equation Native" 流格式为 MathType 专有格式（含字体表、WMF 预览等），生成的公式虽被 Word 识别但不可见。推荐使用 OMML + COM 转换方案。
• convert_to_mathtype.py — MathType 转换独立工具。支持检测 MathType 注册表状态、批量 OMML→MathType 转换，含多种备选策略。
• mathtype_integration.py — MathType 兼容层。提供 MTDisplayEquation 段落样式注入、SEO MTEqn 编号字段、MACROBUTTON MTPlaceRef 占位符、OMML 公式段落构建。

Enhancements:

• formula_inserter.py — 新增 --mathtype 参数：插入公式时使用 MathType 兼容模式（MTDisplayEquation 样式 + SEQ MTEqn 编号 + ZIP 级注入）。

Bug fixes:

• OMML 结构损坏 — 彻底规避 python-docx 对 OMML 元素的破坏：新代码在 ZIP 层直接修改 word/document.xml，使用 re.sub 清除 python-docx 插入的 <m:sSupPr>、<m:sSubPr>、<m:ctrlPr> 等垃圾标签。

New features:

• check-refs command — Automated citation status checking with reference section boundary detection (find_reference_boundary_robust()), per-reference occurrence display (find_citation_occurrences()), --report export, and JSON output support.
• auto-find command — CrossRef-based automatic reference searching with paper title extraction, interactive selection (range, all, none), DOI/title dedup, and auto-reorder after insertion.
• New utility functions — find_reference_boundary_robust() (robust boundary detection), find_citation_occurrences() (citation location lookup), extract_citation_content() (citation number parsing).

Bug fixes:

• Hyperlink styling — Changed from blue + underline to black superscript (inherits document font color, no underline). Added superscript and color parameters to make_hyperlink_element().
• Duplicate hyperlinks — replace_citation_with_hyperlink now only processes direct <w:r> children of <w:p>, skipping runs inside existing <w:hyperlink> elements. Prevents nested hyperlinks that caused visual [1][1] duplicates.
• Cascading reorder bug — cmd_reorder used single-pass sequential replacement, causing [25]→[7]→[8]→...→[25] cascading that corrupted 12 of 25 citation numbers. Fixed with two-phase replacement (temporary marker → final number).
• Reference section hyperlinks — cmd_hyperlink now correctly skips the reference section, preventing false hyperlinks on bibliography entries.
• Adjacent citation dedup — Added dedup_adjacent_citations() function to collapse [1][1][1] → [1] in body text before hyperlink creation.