---
name: Academic Reference Inserter
slug: academic-reference-inserter
category: Automation
description: Inserts, formats, and cross-references academic citations in Word (.docx) documents, supporting Chinese (GB/T 7714) and international (IEEE, APA) formatting standards.
github: "https://github.com/fuwenhao12/academic-ref-inserter"
language: Python
stars: 55
forks: 0
install: "git clone https://github.com/fuwenhao12/academic-ref-inserter"
added: 2026-07-16T03:45:41.876Z
last_synced: 2026-07-16T03:45:41.876Z
canonical_url: "https://dirskills.com/skills/academic-reference-inserter"
---

# Academic Reference Inserter

Inserts, formats, and cross-references academic citations in Word (.docx) documents, supporting Chinese (GB/T 7714) and international (IEEE, APA) formatting standards.

**Install:** `git clone https://github.com/fuwenhao12/academic-ref-inserter`

## README

# Academic Reference Inserter

> **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.

[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.XXXXXX-blue)](https://doi.org/10.5281/zenodo.XXXXXX)

---

## Features

- **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

## Supported Formats

| Format | Region | Common In | Citation Style | Ordering |
|--------|--------|-----------|---------------|----------|
| **GB/T 7714-2015** | China | 计算机工程与应用, 自动化学报 | `[1]` | Sequential |
| **IEEE** | International | Engineering, CS journals | `[1]` | Sequential |
| **APA 7th** | International | Psychology, Education, Business | `(Author, Year)` | Alphabetical |
| **Chicago 17th** | International | Humanities, History | Footnotes/Bib | Alphabetical |
| **MLA 9th** | International | Literature, Arts | `(Author Pg)` | Alphabetical |
| **Harvard** | International | UK/Australia, Social Sci | `(Author, Year)` | Alphabetical |

## Installation

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

# Install dependencies
pip install python-docx
```

## Usage

### Quick Start (Full Pipeline)

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

### Step-by-Step

```bash
# 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
```

### Format Options

```bash
# 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
```

## Example

**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).

## Project Structure

```
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
```

## Validation Checks

After running, the tool verifies:

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

## Running Tests

```bash
cd tests
python test_formats.py
```

## Integration with AI Code Assistants

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

| Assistant | Config File | Auto-Detected |
|-----------|------------|---------------|
| **Cursor** | `.cursorrules` + `.cursor/rules/*.mdc` | ✅ |
| **Claude Code** | `CLAUDE.md` | ✅ |
| **GitHub Copilot** | `.github/copilot-instructions.md` | ✅ |
| **Windsurf** | `.windsurfrules` | ✅ |
| **Aider** (v0.73+) | `CONVENTIONS.md` | ✅ |
| **Continue.dev** | `.continue/config.json` | ✅ (VS Code) |
| **OpenAI Codex CLI** | `AGENTS.md` | ✅ |
| **Kimi Code CLI** (月之暗面) | `.kimi/skills/*/SKILL.md` + `AGENTS.md` | ✅ |
| **Qwen Code** (通义千问) | `.qwen/skills/*/SKILL.md` | ✅ |
| **OpenCode** | `opencode.json` + `AGENTS.md` | ✅ |
| **OpenClaw** (小龙虾) | `~/.openclaw/workspace/` | 需手动配置 |
| **Gemini CLI** | `GEMINI.md` | 手动指定 |
| **Amazon Q Developer** | `AMAZON_Q.md` | VS Code 扩展 |
| **Cline** | `.clinerules` | VS Code 扩展 |
| **Trae** | `SKILL.md` | ✅ |

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

See [AGENTS.md](AGENTS.md) for detailed compatibility information.

## Contributing

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

## License

MIT License - see [LICENSE](LICENSE) for details.

## Citation

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

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

## Changelog

### v1.1.0 (2026-05-31)

**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>` 等垃圾标签。

### v1.0.1 (2026-05-28)

**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.