Reproducible Academic Writing with VS Code, LaTeX, BibTeX, and Git

A paper is more than a formatted PDF. It is a chain from evidence to claims, figures, citations, source text, and a build that another person—or your future self—can inspect. VS Code and LaTeX are useful when they make that chain visible; elaborate editor settings are not the goal.

Begin with claims and evidence

Before polishing prose, write a claim–evidence map. For each planned contribution, record the supporting analysis, figure, experiment, theorem, dataset, or primary reference. Mark the boundary between an observed result, an interpretation, and a limitation. This exposes unsupported statements much earlier than line editing does.

Read strong papers to understand disciplinary conventions, but write from your own evidence map and notes. Do not reproduce another paper’s sentence sequence or replace words inside its prose. Verbatim notes should stay visibly quoted and carry their source until they are either cited correctly or removed. This protects originality while preserving an auditable route back to the evidence.

Treat the paper as a buildable project

Keep the manuscript, bibliography, figures, and build instructions together in a small, predictable tree:

paper/
├── main.tex
├── sections/
├── figures/
├── references.bib
├── README.md
├── .gitignore
└── .vscode/

Use semantic LaTeX structure—sections, labels, cross-references, citation commands, and reusable macros—rather than manually imitating typography. The LaTeX Project documentation is a better reference for document semantics than copied formatting snippets.

The README should name the expected TeX distribution, compiler engine, bibliography backend, entry file, required fonts or external tools, and the single command used to build. If the publisher template imposes a specific workflow, make that constraint explicit instead of hiding it in one workstation’s editor settings.

Let automation drive the build

LaTeX Workshop’s build documentation uses recipes and selects latexmk by default. That is preferable to maintaining a hand-written sequence of LaTeX and bibliography passes: latexmk observes dependencies and invokes the required tools until the document is up to date.

Keep the editor as a front end to a command that also works outside VS Code:

latexmk -pdf -interaction=nonstopmode -file-line-error main.tex

A successful exit is necessary but not sufficient. Read the log for undefined references, missing citations, substituted fonts, overfull boxes, and stale or absent figures. Treat warnings that can change meaning or layout as build failures.

Make the bibliography auditable

Use one reviewed references.bib as the canonical reference database. BibTeX records are convenient to import, but imported metadata is not automatically trustworthy. Check author order, title, venue, year, pages, and DOI against the publisher or another authoritative record before citing it.

Choose stable, human-readable citation keys and avoid duplicate records for preprint and published versions of the same work. Preserve the DOI or canonical publication URL when available. More importantly, attach citations to the exact claim they support; a dense paragraph followed by a stack of loosely related references is not an evidence chain.

Use Git to record decisions

Ignore transient build products, not manuscript evidence:

*.aux
*.blg
*.fls
*.fdb_latexmk
*.log
*.out
*.synctex.gz

Some venues require generated files such as a bibliography output during submission. Archive the submitted package separately or add the required artifact deliberately; do not let a blanket ignore rule decide what constitutes the record.

Before committing, inspect both the working tree and the actual patch. The Git status documentation explains the distinction between working-tree, index, and committed changes.

git status --short
git diff --check
git diff --cached

Prefer small commits that explain an intellectual change—revised evaluation protocol, corrected figure provenance, reconciled reviewer evidence—over messages such as “update paper.” Tag or otherwise archive each submitted version so the PDF, source, bibliography, and reported results can be recovered together.

Define the reproducibility target

For routine collaboration, “reproducible” should at least mean that a clean checkout builds with one documented command and reproduces the paper’s claims, tables, and figures from identified inputs. Record any step that remains manual.

Byte-for-byte output is a stronger target. It may require a pinned TeX distribution or container, exact package and font versions, controlled timestamps, and deterministic figure generation. Use that machinery when the archival or regulatory need justifies it; do not claim exact reproducibility from an unpinned local installation.

Release checklist

Before submission or public release:

1. Build from a clean checkout, not the long-lived working directory.
2. Resolve missing references, citations, figures, and material layout warnings.
3. Trace every nontrivial factual claim to data, analysis, or a primary citation.
4. Check that each figure can be regenerated or has documented provenance.
5. Review the complete Git diff and confirm that no private notes, credentials, or temporary data are included.
6. Archive the exact source package and PDF that were submitted.

This workflow makes writing faster because it removes hidden state. More importantly, it makes the final paper defensible: every claim has an origin, every version has a history, and every build has an explicit path.