mirror/Awesome-CV
1
0
Fork 0
mirror of https://github.com/posquit0/Awesome-CV.git synced 2026-05-03 20:26:34 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore: add project config, Claude instructions, and reference docs

Browse source 
- CLAUDE.md: project guidance for Claude Code (build commands, conventions,
  editing rules, CI notes)
- AGENTS.md: agent-level task conventions for autonomous editing sessions
- .claude/: skills, memory, and settings for Claude Code integration
- docs/: research-backed LaTeX reference examples (small, medium, large-doc
  templates with latexmkrc, local .sty, CI workflow)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mahdi Hoseini 2026-03-04 16:39:18 -08:00
parent 4b3b3ec1a7
commit 8aa1e106be
34 changed files with 1150 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

29
.claude/skills/add-experience/SKILL.md Normal file
View file

@ -0,0 +1,29 @@
---
name: add-experience
description: Add a new work experience entry to the resume
user-invocable: true
---
# Add Experience Entry
Add a new `\cventry` to `src/resume/experience.tex`.
## Steps
1. Ask the user for (if not already provided):
- Job title
- Company name
- Location
- Start month/year and end month/year (use `0/0` for current/present)
- 3-5 bullet points describing achievements (with metrics where possible)
2. Read `src/resume/experience.tex` to understand the current format.
3. Insert the new entry at the correct position (most recent first), using:
- `\cventry{Job title}{Company}{Location}{\acvDateRange{startM}{startY}{endM}{endY}}{...}`
- `\begin{cvitems}` with `\item` bullets
- `\acvDashedSeparator` between entries
4. Build with `make resume.pdf` to verify.
## Rules
- Follow the exact formatting of existing entries in the file.
- Bold key technologies with `\textbf{}`.
- Include quantified impact where possible.

35
.claude/skills/add-section/SKILL.md Normal file
View file

@ -0,0 +1,35 @@
---
name: add-section
description: Add a new section to the resume by creating a .tex file and wiring it into resume.tex
user-invocable: true
---
# Add Resume Section
Create a new section file and integrate it into the resume layout.
## Steps
1. Ask the user for:
- **Section name** (e.g., "Projects", "Certifications", "Volunteering")
- **Column placement**: left column (main content) or right column (sidebar)
- **Content type**: entries (`cventries`), skills (`cvskills`), honors (`cvhonors`), or paragraph (`cvparagraph`)
2. Read `src/resume.tex` to understand the current two-column layout and active `\input` lines.
3. Create `src/resume/<section-name>.tex` with:
- Standard section header comment block
- `\cvsection{Section Title}`
- Appropriate environment with a placeholder entry matching the chosen content type
4. Add `\input{resume/<section-name>.tex}` to `src/resume.tex` in the correct minipage:
- Left minipage (`\acvLeftColumnWidth`) for main content like experience, projects
- Right minipage (`\acvRightColumnWidth`) for sidebar content like skills, education, certifications
5. Build with `make resume.pdf` to verify compilation.
## Rules
- Use lowercase filenames (per CLAUDE.md conventions).
- Follow the existing section file format (see `src/resume/experience.tex`, `src/resume/skills.tex`).
- Place `\input` lines in logical order within the column.

21
.claude/skills/add-skill/SKILL.md Normal file
View file

@ -0,0 +1,21 @@
---
name: add-skill
description: Add a new skill category or update an existing one in the resume
user-invocable: true
---
# Add or Update Skill
Modify `src/resume/skills.tex` to add new skills.
## Steps
1. Read `src/resume/skills.tex` to see existing skill blocks.
2. If the user wants to add to an existing category, append the new skills to that `\skillblock`.
3. If the user wants a new category, add a new `\skillblock{Category}{skills...}` with `\acvDashedSeparatorRoomy` before it.
4. Build with `make resume.pdf` to verify.
## Rules
- Match the existing formatting style.
- Keep skill lists comma-separated within each `\skillblock`.
- Do not duplicate skills already listed.

17
.claude/skills/build/SKILL.md Normal file
View file

@ -0,0 +1,17 @@
---
name: build
description: Build the resume PDF and report any LaTeX errors
user-invocable: true
allowed-tools: Bash(make resume.pdf:*), Bash(make clean:*)
---
# Build Resume
Run `make resume.pdf` to compile the resume. Report whether it succeeded or failed.
If the build fails:
1. Show the relevant LaTeX error lines
2. Suggest a fix based on the error message
3. After fixing, rebuild to confirm
If the build succeeds, confirm with a short message.

55
.claude/skills/ci/SKILL.md Normal file
View file

@ -0,0 +1,55 @@
---
name: ci
description: Generate or update a GitHub Actions workflow for building LaTeX documents
user-invocable: true
---
# Generate CI Workflow
Create or update `.github/workflows/latex.yml` for automated LaTeX builds.
## Steps
1. Check if `.github/workflows/latex.yml` already exists. If so, read it and propose updates.
2. Ask the user for (if not obvious from context):
- **Documents to build**: resume, cv, coverletter, or all
- **Engine**: xelatex (default for this project) or lualatex
- **Triggers**: push, pull_request, or both
3. Generate the workflow based on the pattern from `docs/examples/large-doc/.github/workflows/latex.yml`:
```yaml
name: build-latex
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: xu-cheng/latex-action@v4
with:
root_file: src/resume.tex
work_in_root_file_dir: true
latexmk_use_xelatex: true
- uses: actions/upload-artifact@v4
with:
name: resume-pdf
path: src/resume.pdf
```
4. For multiple documents, add separate steps or a matrix strategy.
5. Write the workflow file and confirm with the user.
## Rules
- Use `xu-cheng/latex-action@v4` (per docs/examples pattern).
- Pin action versions with `@v4` tags.
- Use `-interaction=nonstopmode -file-line-error` flags implicitly (handled by the action).
- This project uses XeLaTeX (`latexmk -xelatex`), so set `latexmk_use_xelatex: true`.
- Include artifact upload so the PDF is downloadable from the Actions run.
## Reference
See `docs/examples/large-doc/.github/workflows/latex.yml` and `docs/latex-research-report.md` CI section.

59
.claude/skills/commit/SKILL.md Normal file
View file

@ -0,0 +1,59 @@
---
name: commit
description: Stage and commit changes following atomic commits and Conventional Commits best practices
user-invocable: true
---
# Commit Changes
Create well-formatted git commits following atomic commit principles and Conventional Commits.
## Steps
1. Run `git status` and `git diff` (staged + unstaged) to review all changes.
2. Run `git log --oneline -10` to match the repo's commit message style.
3. **Group changes into atomic commits.** Each commit must represent exactly one logical change — a single feature, fix, refactor, or chore. If changes span multiple concerns, split them into separate commits.
4. For each atomic commit:
a. Determine the type, scope, and summary:
- **Type**: `feat`, `fix`, `docs`, `refactor`, `style`, `chore`, `test`, `build`
- **Scope**: the area touched (`resume`, `cv`, `coverletter`, `makefile`, `docs`, `skills`, etc.)
- **Summary**: imperative mood, lowercase, no period, max ~72 chars (e.g., "add new experience entry for Neoxi")
b. Stage only the files belonging to this logical change (by name, never `git add -A` or `git add .`).
c. Commit using a HEREDOC:
```
type(scope): short imperative summary
- Explain what changed and why (not how)
- Additional detail if the change is non-obvious
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
```
d. Run `git status` to verify before moving to the next commit.
5. If the user explicitly asks to bundle everything into **one commit**, combine all changes into a single commit with a summary that covers the full scope. Use multiple scopes or a broader scope if needed (e.g., `feat(resume): update experience and skills sections`).
## Commit Message Guidelines
- **Subject line**: imperative mood ("add", "fix", "update"), lowercase after type, no trailing period, max ~72 chars.
- **Body** (optional): explain the "why", not the "what". Wrap at 72 chars. Separate from subject with a blank line.
- **Breaking changes**: prefix body with `BREAKING CHANGE:` if applicable.
- **Footer**: always include the `Co-Authored-By` line.
## Atomic Commit Principles
- Each commit should be self-contained and buildable on its own.
- If you need to refactor before adding a feature, that's two commits: `refactor(scope): ...` then `feat(scope): ...`.
- Group related file changes together (e.g., a new section file + its `\input` line in `resume.tex` = one commit).
- Unrelated changes (e.g., fixing a typo in skills while adding a new experience) should be separate commits.
## Rules
- Follow Conventional Commits as seen in repo history (per CLAUDE.md).
- Never commit files that may contain secrets (`.env`, credentials, tokens).
- Never use `git add -A` or `git add .` — stage specific files by name.
- Never amend previous commits unless explicitly asked.
- Never push unless explicitly asked.
- Never skip hooks (`--no-verify`) unless explicitly asked.
- If a pre-commit hook fails, fix the issue and create a NEW commit (do not amend).
- Pass the commit message via HEREDOC for proper formatting.
- Default to separate atomic commits. Only bundle into one commit if the user explicitly asks.

41
.claude/skills/coverletter/SKILL.md Normal file
View file

@ -0,0 +1,41 @@
---
name: coverletter
description: Generate or update a tailored cover letter for a job posting
user-invocable: true
---
# Generate Cover Letter
Create or update `src/coverletter.tex` with a tailored cover letter for a specific job posting.
## Steps
1. The user provides a job description (pasted text or URL).
2. Read the current resume content to understand the candidate's background:
- `src/resume/summary.tex`
- `src/resume/experience.tex`
- `src/resume/skills.tex`
3. Read `src/coverletter.tex` to understand the existing template structure.
4. Update `src/coverletter.tex`:
- **Personal info**: Use the same info from `src/resume.tex` (name, contact, etc.)
- **Recipient**: Company name and address from the job posting
- **Letter title**: "Job Application for [Role Title]"
- **Opening**: Professional greeting
- **Body sections** using `\lettersection{}`:
- **About Me**: Brief introduction connecting background to the role
- **Why [Company]?**: What draws the candidate to this specific company
- **Why Me?**: Key achievements and skills that match the job requirements
- **Closing**: Professional sign-off with resume enclosure
5. Build with `make coverletter.pdf` to verify compilation.
## Rules
- Never fabricate experience or achievements not present in the resume.
- Keep the tone professional but personable.
- Reference specific technologies and achievements from the resume that match the job requirements.
- Match the accent color to the resume (`acvBlue` / `awesome-red` as configured).
- Keep the letter concise (one page).

42
.claude/skills/lint/SKILL.md Normal file
View file

@ -0,0 +1,42 @@
---
name: lint
description: Lint LaTeX source files for common issues like undefined references, formatting inconsistencies, and prose quality
user-invocable: true
---
# Lint LaTeX Sources
Review `.tex` files under `src/resume/` (and optionally `src/cv/`) for common issues.
## Checks to Perform
1. **LaTeX correctness**
- Unclosed environments or braces
- Undefined or duplicate labels
- Missing `\item` inside list environments (`cvitems`, `itemize`)
- Incorrect nesting of environments
2. **Formatting consistency**
- Consistent use of `\textbf{}` for technology names across all entries
- Consistent date format via `\acvDateRange`
- Matching separators (`\acvDashedSeparator` between entries)
- Two-space indentation inside environments (per CLAUDE.md conventions)
3. **Prose quality**
- Bullet points start with strong action verbs
- Metrics and quantified impact are present where possible
- No orphaned or overly long bullets (aim for 1-2 lines each)
- Consistent tense (past for previous roles, present for current)
- No spelling or grammar errors
4. **Build verification**
- Run `make resume.pdf` and check for warnings (overfull/underfull boxes, undefined references)
- Report any LaTeX warnings from the build log
## Output
Present findings as a categorized list (Errors / Warnings / Suggestions). Do not make changes unless the user asks.
## Reference
See `docs/latex-research-report.md` section on linting for background on chktex and prose-quality patterns.

26
.claude/skills/review/SKILL.md Normal file
View file

@ -0,0 +1,26 @@
---
name: review
description: Review the resume for clarity, impact, consistency, and ATS-friendliness
user-invocable: true
---
# Review Resume
Perform a thorough review of the resume without making changes (unless asked).
## Steps
1. Read all active resume section files:
- `src/resume/summary.tex`
- `src/resume/experience.tex`
- `src/resume/skills.tex`
- `src/resume/education.tex`
- `src/resume/languages.tex`
2. Evaluate against these criteria:
- **Clarity**: Are bullets concise and easy to scan?
- **Impact**: Do bullets lead with results and include metrics?
- **Consistency**: Is tense, formatting, and style uniform across entries?
- **ATS-friendliness**: Are keywords present for common ATS parsers? Are there formatting issues that could confuse parsers?
- **Length**: Does everything fit on one page without feeling cramped?
3. Present findings as a prioritized list of suggestions.
4. Only make edits if the user explicitly asks.

33
.claude/skills/scaffold/SKILL.md Normal file
View file

@ -0,0 +1,33 @@
---
name: scaffold
description: Scaffold a new LaTeX project from small, medium, or large document templates in docs/examples
user-invocable: true
---
# Scaffold LaTeX Project
Generate a new LaTeX project structure based on the reference layouts in `docs/examples/`.
## Steps
1. Ask the user for:
- **Scale**: small (single-file), medium (modular sections), or large (chapters, CI, .sty, glossary)
- **Target directory**: where to create the project
- **Document title and author**
2. Read the matching template from `docs/examples/`:
- `docs/examples/small-doc/` — single `main.tex` + `latexmkrc` + `references.bib`
- `docs/examples/medium-doc/` — `src/main.tex` + `src/sections/` + `latexmkrc` + `bib/`
- `docs/examples/large-doc/` — full structure with `Makefile`, `.github/workflows/latex.yml`, `src/styles/project.sty`, `glossary/`, `figures/`, `build/`
3. Create the file tree in the target directory, substituting title/author into the templates.
4. Confirm the structure with a file listing and suggest the build command.
## Rules
- Follow the exact patterns from the reference examples.
- Use `latexmk` as the build orchestrator (per `docs/latex-research-report.md`).
- For large-doc, include the GitHub Actions workflow with `xu-cheng/latex-action@v4`.
- Keep `hyperref` near the end of the preamble.
- Default to pdfLaTeX for small/medium; LuaLaTeX for large (per research report recommendations).

28
.claude/skills/tailor/SKILL.md Normal file
View file

@ -0,0 +1,28 @@
---
name: tailor
description: Tailor the resume for a specific job posting by adjusting summary, skills, and experience bullets
user-invocable: true
---
# Tailor Resume for Job Posting
The user will provide a job description (pasted text or URL). Adjust the resume to better match the role.
## Steps
1. Read the job description and extract key requirements, technologies, and soft skills.
2. Read the current resume files:
- `src/resume/summary.tex`
- `src/resume/skills.tex`
- `src/resume/experience.tex`
3. Adjust the resume:
- **Summary**: Rewrite to align with the target role's language and priorities.
- **Skills**: Reorder skill blocks so the most relevant categories appear first. Add missing skills the candidate actually has.
- **Experience bullets**: Reword to emphasize achievements matching the job requirements. Do NOT fabricate experience.
4. Build with `make resume.pdf` to verify compilation.
5. Summarize the changes made.
## Rules
- Never invent experience, skills, or metrics the candidate does not have.
- Preserve the existing LaTeX formatting conventions (see CLAUDE.md).
- Keep the resume to one page.

38
AGENTS.md Normal file
View file

@ -0,0 +1,38 @@
# Repository Guidelines
## Project Structure & Module Organization
- `src/` is the CV codebase. Roots: `src/resume.tex`, `src/cv.tex`, and `src/coverletter.tex`; sections live in `src/resume/*.tex` and `src/cv/*.tex`.
- `src/assets/` stores images used by the documents; `build/` contains copied artifacts from `make build`.
- `docs/examples/` is the reference lab: `small-doc/` (single-file), `medium-doc/` (modular `\input` sections), and `large-doc/` (chapters, local `.sty`, glossary, CI/Makefile).
- `awesome-cv.cls` is a shared class dependency; treat edits as cross-document changes.
## Build, Test, and Development Commands
- `make`: Compile all top-level documents (`resume.pdf`, `cv.pdf`, `coverletter.pdf`) using `latexmk -xelatex`.
- `make resume.pdf` / `make cv.pdf` / `make coverletter.pdf`: Compile one document only.
- `make build`: Copy `src/resume.pdf` into `build/` with the release filename.
- `make clean`: Remove generated PDFs and LaTeX auxiliary files.
- Example builds from `docs/examples/`: `latexmk -pdf -interaction=nonstopmode -file-line-error docs/examples/small-doc/main.tex`, `latexmk -cd -pdf -interaction=nonstopmode -file-line-error docs/examples/medium-doc/src/main.tex`, `make -C docs/examples/large-doc pdf`, and `make -C docs/examples/large-doc glossary`.
## Coding Style & Naming Conventions
- Keep files UTF-8 and compatible with XeLaTeX.
- Follow existing LaTeX style: two-space indentation inside environments and concise `%` section comments.
- Keep section filenames short and lowercase (for example, `summary.tex`, `languages.tex`).
- Prefer modular content with `\input`; reserve `\include` for chapter-scale documents where `\includeonly` is needed.
- Keep shared macros/layout policy in local `.sty` files (see `docs/examples/large-doc/src/styles/project.sty`) and load `hyperref` near the end of the preamble.
- Keep typography defaults like `microtype` and `booktabs` unless a document has a specific reason to diverge.
## Testing Guidelines
- There is no unit-test framework; successful compilation is the primary check.
- Before submitting changes, run `make clean && make`.
- Use `-interaction=nonstopmode -file-line-error` for actionable failures.
- Validate generated PDFs in `src/` for layout regressions (overflow, spacing, page breaks, alignment, table quality).
- CI compiles deterministic root files (`make` in this repo; `root_file: src/main.tex` in the large example workflow).
## Commit & Pull Request Guidelines
- Use Conventional Commits, matching existing history (for example, `feat(resume): ...`, `fix(makefile): ...`, `docs(readme): ...`).
- Keep commit scopes tied to touched areas (`resume`, `cv`, `makefile`, `README`, etc.).
- PRs should include a short summary, linked issue (if any), and updated PDFs or screenshots when visual output changes.
- Confirm local build success (`make`) in the PR description.
## Security & Tooling Notes
- Default to CI-safe builds without unrestricted shell-escape. For code blocks, prefer `listings`; use `minted` only when the team explicitly accepts its external tooling and shell-escape requirements.

67
CLAUDE.md Normal file
View file

@ -0,0 +1,67 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working in this repository.
## Project Overview
LaTeX-based CV/resume/cover-letter project built on [Awesome-CV](https://github.com/posquit0/Awesome-CV). The main build uses `latexmk -xelatex`.
## Repository Map
- `src/`: production documents.
- roots: `src/resume.tex`, `src/cv.tex`, `src/coverletter.tex`
- modular sections: `src/resume/*.tex`, `src/cv/*.tex`
- assets: `src/assets/`
- `build/`: packaged artifact output from `make build`.
- `awesome-cv.cls`: shared class; changes affect all documents.
- `docs/examples/`: research-backed reference patterns:
- `small-doc/` (single-file + `latexmkrc`)
- `medium-doc/` (modular `\input` structure)
- `large-doc/` (chapter layout, local `.sty`, glossary, CI workflow)
## Build and Debug Commands
```bash
make # build resume.pdf, cv.pdf, coverletter.pdf
make resume.pdf # build resume only
make cv.pdf # build cv only
make coverletter.pdf # build cover letter only
make build # copy src/resume.pdf to build/ release filename
make clean # remove generated PDFs and aux files
```
Example commands from `docs/examples`:
```bash
latexmk -pdf -interaction=nonstopmode -file-line-error docs/examples/small-doc/main.tex
latexmk -cd -pdf -interaction=nonstopmode -file-line-error docs/examples/medium-doc/src/main.tex
make -C docs/examples/large-doc pdf
make -C docs/examples/large-doc glossary
```
## Editing Conventions
- Keep files UTF-8 and XeLaTeX-compatible.
- Use two-space indentation inside LaTeX environments.
- Keep filenames lowercase and focused (`summary.tex`, `languages.tex`).
- Prefer `\input` for modular composition; reserve `\include` for chapter-level split with `\includeonly`.
- Keep shared macros in local `.sty` files when logic grows (see `docs/examples/large-doc/src/styles/project.sty`).
- Load `hyperref` near the end of the preamble.
- Keep `microtype` and `booktabs` unless there is a specific layout reason to remove them.
## Validation and CI
- Primary quality gate is successful compile plus visual PDF review.
- Run `make clean && make` before finalizing edits.
- Use `-interaction=nonstopmode -file-line-error` for actionable failures.
- CI compiles deterministic roots (`make` here; `root_file: src/main.tex` in the large-doc example workflow).
## Commits and PRs
- Follow Conventional Commits seen in repo history (`feat(resume): ...`, `fix(makefile): ...`, `docs(readme): ...`).
- Use scoped messages for the touched area (`resume`, `cv`, `makefile`, `docs`).
- Include summary, linked issue (if any), and updated PDFs/screenshots when visual output changes.
## Security Note
Default to CI-safe builds without unrestricted shell-escape. Prefer `listings`; use `minted` only when shell-escape and external tooling are explicitly approved.

17
docs/examples/large-doc/.github/workflows/latex.yml vendored Normal file
View file

@ -0,0 +1,17 @@
name: build-latex
on:
push:
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Compile LaTeX
uses: xu-cheng/latex-action@v4
with:
root_file: src/main.tex
work_in_root_file_dir: true
latexmk_use_lualatex: true

14
docs/examples/large-doc/Makefile Normal file
View file

@ -0,0 +1,14 @@
LATEXMK=latexmk
MAIN=src/main.tex
.PHONY: pdf clean glossary
pdf:
$(LATEXMK) -lualatex -interaction=nonstopmode -file-line-error $(MAIN)
glossary:
makeglossaries src/main
clean:
$(LATEXMK) -C $(MAIN)
rm -f src/main.acn src/main.acr src/main.alg src/main.glo src/main.gls src/main.ist

6
docs/examples/large-doc/bib/references.bib Normal file
View file

@ -0,0 +1,6 @@
@manual{biblatex,
title = {The biblatex Package},
author = {Philipp Lehman and Joseph Wright and Philip Kime and others},
year = {2025},
url = {https://ctan.org/pkg/biblatex}
}

1
docs/examples/large-doc/glossary/acronyms.tex Normal file
View file

@ -0,0 +1 @@
\newacronym{ci}{CI}{continuous integration}

2
docs/examples/large-doc/src/appendix/a-reproducibility.tex Normal file
View file

@ -0,0 +1,2 @@
\chapter{Reproducibility Notes}
Build commands are pinned in \texttt{Makefile} and CI workflow config.

2
docs/examples/large-doc/src/chapters/01-intro.tex Normal file
View file

@ -0,0 +1,2 @@
\chapter{Introduction}
We define CI as continuous integration. See Table~\ref{tab:baseline}.

16
docs/examples/large-doc/src/chapters/02-methods.tex Normal file
View file

@ -0,0 +1,16 @@
\chapter{Methods}
The workflow uses explicit build orchestration and modular files.
\begin{table}[htbp]
\centering
\begin{tabular}{ll}
\toprule
Component & Choice \\
\midrule
Engine & LuaLaTeX \\
Bibliography & biblatex+biber \\
\bottomrule
\end{tabular}
\caption{Baseline choices.}
\label{tab:baseline}
\end{table}

2
docs/examples/large-doc/src/chapters/03-results.tex Normal file
View file

@ -0,0 +1,2 @@
\chapter{Results}
The repository structure enables per-file reviews and targeted ownership.

4
docs/examples/large-doc/src/frontmatter/title.tex Normal file
View file

@ -0,0 +1,4 @@
\maketitle
\begin{abstract}
This project demonstrates a large-repo LaTeX layout with modular chapters, bibliography, and acronyms.
\end{abstract}

32
docs/examples/large-doc/src/main.tex Normal file
View file

@ -0,0 +1,32 @@
\documentclass[12pt]{report}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage[english]{babel}
\usepackage[final]{microtype}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage[hidelinks]{hyperref}
\usepackage{styles/project}
\title{Large Document Example}
\author{Your Team}
\date{\today}
\begin{document}
\pagenumbering{roman}
\input{frontmatter/title}
\tableofcontents
\clearpage
\pagenumbering{arabic}
\input{chapters/01-intro}
\input{chapters/02-methods}
\input{chapters/03-results}
\appendix
\input{appendix/a-reproducibility}
\end{document}

4
docs/examples/large-doc/src/styles/project.sty Normal file
View file

@ -0,0 +1,4 @@
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{project}[2026/03/04 Project-local macros]
\newcommand{\ProjectName}{LargeDocExample}

8
docs/examples/medium-doc/bib/references.bib Normal file
View file

@ -0,0 +1,8 @@
@article{knuth1986,
author = {Donald E. Knuth},
title = {The {\TeX}book and Beyond},
journal = {TUGboat},
year = {1986},
volume = {7},
number = {3}
}

4
docs/examples/medium-doc/latexmkrc Normal file
View file

@ -0,0 +1,4 @@
$pdflatex = 'pdflatex -interaction=nonstopmode -file-line-error %O %S';
$pdf_mode = 1;
$bibtex_use = 2;
$max_repeat = 5;

23
docs/examples/medium-doc/src/main.tex Normal file
View file

@ -0,0 +1,23 @@
\documentclass[11pt]{report}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage[final]{microtype}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{hyperref}
\title{Medium Document Example}
\author{Your Name}
\date{\today}
\begin{document}
\maketitle
\tableofcontents
\input{sections/intro}
\input{sections/method}
\input{sections/results}
\end{document}

2
docs/examples/medium-doc/src/sections/intro.tex Normal file
View file

@ -0,0 +1,2 @@
\chapter{Introduction}
Modular files keep merge conflicts smaller and enable focused reviews.

2
docs/examples/medium-doc/src/sections/method.tex Normal file
View file

@ -0,0 +1,2 @@
\chapter{Method}
This chapter demonstrates splitting technical content across files.

13
docs/examples/medium-doc/src/sections/results.tex Normal file
View file

@ -0,0 +1,13 @@
\chapter{Results}
\begin{table}[htbp]
\centering
\begin{tabular}{lr}
\toprule
Metric & Value \\
\midrule
Accuracy & 0.95 \\
Runtime (s) & 1.3 \\
\bottomrule
\end{tabular}
\caption{Example table using \texttt{booktabs}.}
\end{table}

3
docs/examples/small-doc/latexmkrc Normal file
View file

@ -0,0 +1,3 @@
$pdf_mode = 1;
$bibtex_use = 2;
$max_repeat = 5;

17
docs/examples/small-doc/main.tex Normal file
View file

@ -0,0 +1,17 @@
\documentclass[11pt]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage[final]{microtype}
\usepackage{hyperref}
\title{Small Document Example}
\author{Your Name}
\date{\today}
\begin{document}
\maketitle
This is a minimal small-document layout.
\end{document}

6
docs/examples/small-doc/references.bib Normal file
View file

@ -0,0 +1,6 @@
@book{lamport1994,
author = {Leslie Lamport},
title = {LaTeX: A Document Preparation System},
year = {1994},
publisher = {Addison-Wesley}
}

481
docs/latex-research-report.md Normal file
View file

@ -0,0 +1,481 @@
# LaTeX Engineering Research Report
## 1) Executive summary
- For most new technical documents in 2026, defaulting to `latexmk` orchestration and a modular repo layout gives the best reliability-to-complexity ratio; `latexmk` is explicitly designed to run the needed pass graph automatically ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [CTAN latexmk](https://ctan.org/pkg/latexmk)).
- Engine choice should be requirement-driven: `pdfLaTeX` for conservative portability, `LuaLaTeX`/`XeLaTeX` for modern OpenType and Unicode workflows via `fontspec` ([Overleaf compiler guide](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler%23Other_compilers), [CTAN fontspec](https://ctan.org/pkg/fontspec)).
- `\include` and `\input` are not interchangeable: `\include` forces page breaks and separate `.aux` files and is intended for top-level units; `\input` is finer-grained and nestable ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [TeX FAQ](https://texfaq.org/FAQ-include)).
- Preamble stability is mostly about package order and option ownership; `hyperref` documentation still frames it as a near-last package with explicit compatibility exceptions ([hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html), [CTAN hyperref](https://ctan.org/pkg/hyperref)).
- For bibliography, `biblatex`+`biber` is the most capable modern stack (Unicode, localization, data model control), while classic BibTeX remains simpler and widely supported in legacy templates ([CTAN biblatex](https://ctan.org/pkg/biblatex), [biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf), [LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)).
- Typography quality gains from `microtype` are high impact and low risk in production documents ([CTAN microtype](https://ctan.org/pkg/microtype)).
- For code, `listings` is safer/default CI-friendly; `minted` is higher fidelity but depends on external tooling and shell-escape semantics ([CTAN listings](https://ctan.org/pkg/listings), [CTAN minted](https://ctan.org/pkg/minted), [minted manual](https://tug.ctan.org/macros/latex/contrib/minted/minted.pdf), [TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog)).
- Lint + prose quality should be layered: TeX lint (`chktex`) + language/style lint (`Textidote` and/or `Vale`) + pre-commit hooks ([CTAN chktex](https://ctan.org/pkg/chktex), [Textidote](https://github.com/sylvainhalle/textidote), [Vale docs](https://vale.sh/docs), [pre-commit docs](https://pre-commit.com/)).
- CI should compile deterministic targets from explicit roots; `xu-cheng/latex-action` provides a practical baseline for GitHub Actions with root selection and engine options ([latex-action](https://github.com/xu-cheng/latex-action)).
- The best long-term pattern is: small documents stay minimal; medium/large documents migrate shared logic into local `.sty` and enforce build/lint in CI ([CTAN xparse](https://ctan.org/pkg/xparse), [CTAN arara](https://ctan.org/pkg/arara), [Overleaf latexmkrc](https://docs.overleaf.com/managing-projects-and-files/the-latexmkrc-file)).
## 2) Research methodology
### Search strategy (queries used)
- `latex2e include input includeonly`
- `hyperref load order package compatibility`
- `latexmk manual automatic runs`
- `minted shell escape pygments`
- `biblatex biber backend bibtex differences`
- `glossaries makeglossaries xindy makeindex`
- `chktex lacheck textidote vale pre-commit`
- `latex github actions root_file latex-action`
- `awesome-cv repository latex`
- `scientific thesis template latex repository`
Primary retrieval came from package docs, CTAN package pages, TeX FAQ, the LaTeX2e reference manual, and official tooling docs.
### Source selection criteria
- Included as authoritative:
- Official package documentation and CTAN entries (maintainer-defined behavior and scope).
- LaTeX Project and TeX ecosystem docs (manual semantics, build behavior).
- TeX FAQ for canonical operational guidance.
- Overleaf docs only for workflow clarification and compiler/tooling operational notes.
- Official tool/project docs for CI/lint (`pre-commit`, `Vale`, `latex-action`).
- Excluded:
- Unmaintained blogs, SEO posts, and uncited forum summaries.
- Advice contradicting package manuals without technical evidence.
### Conflict resolution policy
- Priority order: package manual > CTAN package metadata > LaTeX2e/TeX FAQ semantics > operational docs (Overleaf/tool docs).
- When sources differed:
- I preferred the most recent package/manual statement.
- I marked operational guidance as context-dependent when not guaranteed by core TeX semantics.
- I reduced confidence and marked “uncited” where no stable primary source was available.
## 3) Findings
### A. Engines and Unicode (pdfLaTeX vs XeLaTeX vs LuaLaTeX)
- `pdfLaTeX` is still the conservative baseline for compatibility with older templates and package assumptions, while XeLaTeX/LuaLaTeX are better for Unicode/OpenType-heavy projects ([Overleaf compiler guide](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler%23Other_compilers), [CTAN fontspec](https://ctan.org/pkg/fontspec)).
- `fontspec` is designed for XeTeX/LuaTeX and is the practical trigger condition to choose those engines ([CTAN fontspec](https://ctan.org/pkg/fontspec)).
- `unicode-math` is explicitly for Unicode math font workflows and therefore aligns with Unicode engines, not classic `pdfLaTeX` pipelines ([CTAN unicode-math](https://ctan.org/pkg/unicode-math)).
- Language handling is no longer binary: `babel` remains central and supports modern engines; `polyglossia` is a common Xe/Lua path when its language model fits project needs ([CTAN babel](https://ctan.org/pkg/babel), [CTAN polyglossia](https://ctan.org/pkg/polyglossia)).
Opinionated conclusion: default to `LuaLaTeX` when you need modern font control or multilingual Unicode; otherwise keep `pdfLaTeX` for speed and compatibility.
### B. Preamble design, package ordering, and conflict management
- The hyperref maintainers still document package compatibility/load-order caveats and recommend near-end loading with specific exceptions ([hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html)).
- Preamble complexity is a maintenance risk; controlling options centrally and minimizing overlapping package responsibility reduces hidden interactions ([CTAN hyperref](https://ctan.org/pkg/hyperref), [LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)).
- For team repos, move custom macros and styling into project-local packages (`src/styles/*.sty`) to separate policy from content and reduce preamble drift ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)).
### C. Modularity patterns: `\input` vs `\include`, file trees, per-chapter builds
- `\include` forces `\clearpage`, writes separate aux files, cannot be nested, and supports selective compilation with `\includeonly` ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)).
- TeX FAQ guidance matches this: use `\include` for major units (chapters), `\input` for fine-grained composition ([TeX FAQ](https://texfaq.org/FAQ-include)).
- Per-chapter builds are best implemented as explicit tool behavior (`latexmk -cd`, subdocument tooling) rather than ad hoc path hacks ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt)).
Practical rule: use `\input` by default; reserve `\include` for chapter-level builds where `\includeonly` is valuable.
### D. Macros and local packages: when to create `.sty`, robust commands, xparse
- `xparse` as a separate package is marked obsolete in the CTAN entry because command parsing interfaces are now in the LaTeX kernel; this is a key modernization signal ([CTAN xparse](https://ctan.org/pkg/xparse)).
- For shared team macros, a local `.sty` with `\ProvidesPackage` is a cleaner maintenance boundary than accumulating raw preamble definitions across files ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)).
- Robust command strategy still matters for moving arguments and hyperlinks; prefer modern declarative command definitions and avoid fragile legacy macro patterns where possible ([hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html), [CTAN xparse](https://ctan.org/pkg/xparse)).
### E. Typography and layout quality: microtype, fonts, spacing, floats
- `microtype` is one of the highest-value packages for production typography quality (protrusion/expansion and related micro-typographic controls) ([CTAN microtype](https://ctan.org/pkg/microtype)).
- Table quality is materially better with `booktabs`; package guidance emphasizes typographic rules over vertical-line grids ([CTAN booktabs](https://ctan.org/pkg/booktabs)).
- Page geometry should be managed explicitly with `geometry` rather than class defaults if output constraints matter (conference, print, institutional templates) ([CTAN geometry](https://ctan.org/pkg/geometry)).
- Float placement should be tuned conservatively (`htbp` defaults, deliberate breaks), with package additions only when baseline algorithms fail (uncited; moderate confidence).
### F. Tables/figures/diagrams/code listings: best packages, tradeoffs, pitfalls
- Use `graphicx` as the default for raster/vector inclusion and transformation ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)).
- Use `booktabs` for publication-grade tables; avoid “spreadsheet style” ruled boxes ([CTAN booktabs](https://ctan.org/pkg/booktabs)).
- Diagram stack: `pgf/tikz` remains the most integrated native graphics ecosystem for complex technical diagrams ([CTAN pgf](https://ctan.org/pkg/pgf)).
- Code listing decision:
- `listings`: pure-TeX, no external process dependency, safer CI default ([CTAN listings](https://ctan.org/pkg/listings)).
- `minted`: better syntax highlighting, but depends on Pygments and shell-escape behavior ([CTAN minted](https://ctan.org/pkg/minted), [minted manual](https://tug.ctan.org/macros/latex/contrib/minted/minted.pdf), [TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog)).
### G. Citations and bibliographies: BibTeX vs biblatex/biber, DOI/URL handling
- Classic BibTeX flow (`latex` -> `bibtex` -> `latex` -> `latex`) remains canonical and still works broadly with legacy styles ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)).
- `biblatex` is architecturally more capable (style/data model separation, localization, backend choice), with Biber as its full-feature backend ([CTAN biblatex](https://ctan.org/pkg/biblatex), [biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf), [biber manual](https://mirrors.ctan.org/biblio/biber/base/documentation/biber.pdf)).
- `biblatex` can run with BibTeX backend but with reduced capabilities; teams should treat this as compatibility mode, not target architecture ([biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf)).
- DOI/URL/eprint display is policy-driven and configurable in modern bibliography stacks; decide and enforce at style level in repo standards ([biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf)).
### H. Glossaries/acronyms/indexes: workflows and build steps
- `glossaries` is a mature workflow package but requires external indexing/sorting steps; treat it as multi-step build architecture, not one-pass LaTeX ([CTAN glossaries](https://ctan.org/pkg/glossaries), [CTAN glossaries-user](https://ctan.org/pkg/glossaries-user)).
- Index management is easier with tooling packages like `imakeidx`, but CI must explicitly run required indexing commands ([CTAN imakeidx](https://ctan.org/pkg/imakeidx)).
- For large repos, encapsulate glossary/index steps in Make/latexmk/arara rules; avoid manual one-off command sequences ([CTAN arara](https://ctan.org/pkg/arara), [latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt)).
### I. Tooling and automation: latexmk, arara, Makefile/justfile, Docker, CI
- `latexmk` should be the default orchestrator because it tracks dependencies and rerun conditions automatically ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [CTAN latexmk](https://ctan.org/pkg/latexmk)).
- `arara` is useful when you want directives inside TeX sources rather than external scripts; this is a workflow style choice, not a universal replacement ([CTAN arara](https://ctan.org/pkg/arara)).
- Overleaf explicitly supports project-level `latexmkrc`, which helps align local and cloud build behavior ([Overleaf latexmkrc](https://docs.overleaf.com/managing-projects-and-files/the-latexmkrc-file)).
- GitHub Actions baseline for LaTeX is straightforward with `latex-action` root selection and engine toggles ([latex-action](https://github.com/xu-cheng/latex-action)).
- Docker-based pinning is often useful for version stability, but exact image strategy is environment-dependent (uncited; moderate confidence).
### J. Linting and style: chktex, lacheck, TeXtidote, Vale, pre-commit
- `chktex` is the practical TeX syntax/style lint baseline; high signal for common anti-patterns and mistakes ([CTAN chktex](https://ctan.org/pkg/chktex)).
- `lacheck` exists but is older and narrower in scope; use mainly for legacy parity, not as sole lint gate ([CTAN lacheck](https://ctan.org/pkg/lacheck)).
- `Textidote` adds language/prose checks around TeX workflows and can complement TeX-specific linting ([Textidote](https://github.com/sylvainhalle/textidote)).
- `Vale` provides customizable editorial style rules and integrates cleanly in docs CI pipelines ([Vale docs](https://vale.sh/docs)).
- `pre-commit` is the easiest way to enforce consistent checks locally before push ([pre-commit docs](https://pre-commit.com/)).
### K. Debugging playbook: reading logs, common errors, checklists
- Build with file/line reporting (`-file-line-error`) and non-interactive mode in CI to make failures actionable ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt)).
- First-failure debugging still beats cascade chasing: fix the earliest fatal error in log order, then rebuild (uncited; high confidence from tool behavior).
- Common failure classes to triage first: missing package/font files, undefined control sequences, path errors in modular repos, stale aux state ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [TeX FAQ](https://texfaq.org/)).
- Use selective compile (`\includeonly`, subset build targets) to shorten turnaround in large projects ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)).
### L. Security: shell-escape risks, minted, safe CI defaults
- Executing external programs from TeX is a known security-sensitive area; shell escape is intentionally constrained by default in typical setups ([TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog)).
- `minted` explicitly relies on external tooling and therefore increases build attack surface relative to pure-TeX listing packages ([minted manual](https://tug.ctan.org/macros/latex/contrib/minted/minted.pdf), [CTAN minted](https://ctan.org/pkg/minted)).
- Safe CI default: avoid unrestricted shell-escape unless required; if required, isolate CI permissions and dependency set (uncited; moderate confidence).
## 4) “Gold standard” repo layouts (copy-paste)
All layouts below are implemented in this repo under [`docs/examples/`](/Users/mahdi/Work/Awesome-CV/docs/examples).
### Small doc
#### File tree
```text
docs/examples/small-doc/
├── latexmkrc
├── main.tex
└── references.bib
```
#### Minimal runnable files
`main.tex`
```tex
\documentclass[11pt]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage[final]{microtype}
\usepackage{hyperref}
\title{Small Document Example}
\author{Your Name}
\date{\today}
\begin{document}
\maketitle
This is a minimal small-document layout.
\end{document}
```
`latexmkrc`
```perl
$pdf_mode = 1;
$bibtex_use = 2;
$max_repeat = 5;
```
#### Build commands
- macOS/Linux: `latexmk -pdf -interaction=nonstopmode -file-line-error main.tex`
- Windows (PowerShell): `latexmk -pdf -interaction=nonstopmode -file-line-error .\main.tex`
#### Git-friendly rules
- One sentence per line in prose-heavy documents to reduce diff noise.
- Label format: `sec:...`, `fig:...`, `tab:...`, `eq:...`.
- Keep filenames lowercase with hyphens.
- Keep package imports sorted/grouped by concern (encoding, typography, layout, refs).
### Medium doc
#### File tree
```text
docs/examples/medium-doc/
├── bib/
│ └── references.bib
├── latexmkrc
└── src/
├── main.tex
└── sections/
├── intro.tex
├── method.tex
└── results.tex
```
#### Minimal runnable files
`src/main.tex`
```tex
\documentclass[11pt]{report}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage[final]{microtype}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{hyperref}
\title{Medium Document Example}
\author{Your Name}
\date{\today}
\begin{document}
\maketitle
\tableofcontents
\input{sections/intro}
\input{sections/method}
\input{sections/results}
\end{document}
```
`src/sections/results.tex`
```tex
\chapter{Results}
\begin{table}[htbp]
\centering
\begin{tabular}{lr}
\toprule
Metric & Value \\
\midrule
Accuracy & 0.95 \\
Runtime (s) & 1.3 \\
\bottomrule
\end{tabular}
\caption{Example table using \texttt{booktabs}.}
\end{table}
```
#### Build commands
- macOS/Linux: `latexmk -cd -pdf -interaction=nonstopmode -file-line-error src/main.tex`
- Windows (PowerShell): `latexmk -cd -pdf -interaction=nonstopmode -file-line-error .\src\main.tex`
#### Git-friendly rules
- Keep each section/chapter in its own file.
- Never mix macro definitions with content files.
- Avoid line-wrap churn in tables/equations; prefer stable formatting conventions.
- CI compiles only canonical root (`src/main.tex`).
### Large doc (chapters, figures, bib, glossary, code)
#### File tree
```text
docs/examples/large-doc/
├── .github/workflows/latex.yml
├── Makefile
├── bib/
│ └── references.bib
├── glossary/
│ └── acronyms.tex
├── build/
├── figures/
└── src/
├── main.tex
├── appendix/
│ └── a-reproducibility.tex
├── chapters/
│ ├── 01-intro.tex
│ ├── 02-methods.tex
│ └── 03-results.tex
├── frontmatter/
│ └── title.tex
└── styles/
└── project.sty
```
#### Minimal runnable files
`src/main.tex`
```tex
\documentclass[12pt]{report}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage[english]{babel}
\usepackage[final]{microtype}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage[hidelinks]{hyperref}
\usepackage{styles/project}
\title{Large Document Example}
\author{Your Team}
\date{\today}
\begin{document}
\pagenumbering{roman}
\input{frontmatter/title}
\tableofcontents
\clearpage
\pagenumbering{arabic}
\input{chapters/01-intro}
\input{chapters/02-methods}
\input{chapters/03-results}
\appendix
\input{appendix/a-reproducibility}
\end{document}
```
`src/styles/project.sty`
```tex
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{project}[2026/03/04 Project-local macros]
\newcommand{\ProjectName}{LargeDocExample}
```
`Makefile`
```make
LATEXMK=latexmk
MAIN=src/main.tex
.PHONY: pdf clean
pdf:
$(LATEXMK) -cd -pdf -interaction=nonstopmode -file-line-error $(MAIN)
clean:
$(LATEXMK) -cd -C $(MAIN)
```
`.github/workflows/latex.yml`
```yaml
name: build-latex
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: xu-cheng/latex-action@v4
with:
root_file: src/main.tex
work_in_root_file_dir: true
```
#### Build commands
- macOS/Linux: `make pdf`
- Windows (PowerShell without make): `latexmk -cd -pdf -interaction=nonstopmode -file-line-error .\src\main.tex`
- Windows (with GNU Make): `make pdf`
#### Git-friendly rules
- Prefix chapter files with numeric order (`01-...`, `02-...`) for stable review ordering.
- Keep all local reusable commands in `src/styles/*.sty`.
- Keep figures immutable by name; never overwrite semantics under same filename.
- Require CI on every PR for compile + lint.
Supporting evidence for layout decisions: `\input`/`\include` semantics and `\includeonly` ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [TeX FAQ](https://texfaq.org/FAQ-include)), automation with `latexmk` ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt)), CI action root-file model ([latex-action](https://github.com/xu-cheng/latex-action)).
## 5) Package recommendations (opinionated)
| Category | Package | Purpose | When to avoid | Alternatives | Sources |
|---|---|---|---|---|---|
| Typography | `microtype` | Better line breaks and text color | Rare engine/path edge cases | none practical at same maturity | [CTAN microtype](https://ctan.org/pkg/microtype) |
| Links/refs | `hyperref` | Cross-doc links and PDF metadata | Never omit in digital docs unless class forbids | none (core baseline) | [CTAN hyperref](https://ctan.org/pkg/hyperref), [hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html) |
| Smart refs | `cleveref` | Auto-typed references (`Figure`, `Table`, etc.) | Very small docs or strict class conflicts | manual `\ref` wrappers | [CTAN cleveref](https://ctan.org/pkg/cleveref) |
| Tables | `booktabs` | Typographic-quality horizontal rules | Spreadsheet-like dense matrix tables | `tabularray` (context-dependent, uncited) | [CTAN booktabs](https://ctan.org/pkg/booktabs) |
| Page layout | `geometry` | Explicit margin/layout control | Fixed-template venues that forbid overrides | class defaults | [CTAN geometry](https://ctan.org/pkg/geometry) |
| Graphics | `graphicx` | Standard image inclusion | practically never | none | [LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html) |
| Bibliography | `biblatex` + `biber` | Modern citation model | Legacy-only journals with fixed BibTeX styles | BibTeX + `natbib` | [CTAN biblatex](https://ctan.org/pkg/biblatex), [biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf), [biber manual](https://mirrors.ctan.org/biblio/biber/base/documentation/biber.pdf) |
| Code blocks | `listings` | Shell-escape-free syntax blocks | Need Pygments-grade highlighting | `minted` | [CTAN listings](https://ctan.org/pkg/listings), [CTAN minted](https://ctan.org/pkg/minted) |
| Glossary | `glossaries` | Acronyms/terms indexes | Tiny docs with no term management | manual acronym macros | [CTAN glossaries](https://ctan.org/pkg/glossaries) |
| Build | `latexmk` | Automatic multi-pass orchestration | Edge workflows needing explicit low-level script control | `arara`, Make | [CTAN latexmk](https://ctan.org/pkg/latexmk), [latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt) |
| Build directives | `arara` | Source-embedded build recipes | Teams preferring externalized build scripts only | Make/Just + latexmk | [CTAN arara](https://ctan.org/pkg/arara) |
| TeX lint | `chktex` | Fast static checks | none; tune rules instead | `lacheck` (legacy) | [CTAN chktex](https://ctan.org/pkg/chktex), [CTAN lacheck](https://ctan.org/pkg/lacheck) |
| Prose lint | `Vale` / `Textidote` | Style and grammar checks | math-heavy docs where prose lint noise dominates | selective rule scopes | [Vale docs](https://vale.sh/docs), [Textidote](https://github.com/sylvainhalle/textidote) |
## 6) Decision tree (engine, bib system, code listings, modularization)
```text
Start
|
+-- Need system/OpenType fonts, multilingual Unicode-heavy content, or unicode math?
| |
| +-- Yes -> LuaLaTeX (default) or XeLaTeX if toolchain requires it
| | Sources: fontspec, unicode-math, compiler guides
| |
| +-- No -> pdfLaTeX
|
+-- Need advanced citation localization/model customization?
| |
| +-- Yes -> biblatex + biber
| |
| +-- No -> BibTeX (+ natbib if needed by template)
|
+-- Need high-fidelity syntax highlighting from Pygments themes?
| |
| +-- Yes -> minted (accept shell-escape/tooling constraints)
| |
| +-- No -> listings (safer CI baseline)
|
+-- Project scale?
|
+-- Small (<20 pages, low collaboration) -> single root + minimal includes
|
+-- Medium (multi-author sections) -> src/sections + \input + latexmk -cd
|
+-- Large (chapters, frontmatter, CI, reusable macros) ->
src/{chapters,frontmatter,styles} + local .sty + CI compile root
```
References: [fontspec](https://ctan.org/pkg/fontspec), [unicode-math](https://ctan.org/pkg/unicode-math), [biblatex](https://ctan.org/pkg/biblatex), [LaTeX2e BibTeX flow](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [listings](https://ctan.org/pkg/listings), [minted](https://ctan.org/pkg/minted), [TeX FAQ include](https://texfaq.org/FAQ-include).
## 7) Myths vs reality
1. Myth: “`\include` is just like `\input` but cleaner.” Reality: `\include` forces page breaks and has separate aux behavior; semantics differ materially ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [TeX FAQ](https://texfaq.org/FAQ-include)).
2. Myth: “Hyperref can be loaded anywhere.” Reality: compatibility/load-order constraints are explicitly documented; near-last loading remains standard guidance ([hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html)).
3. Myth: “BibTeX is obsolete and always wrong.” Reality: BibTeX is still valid in many legacy/journal workflows; `biblatex+biber` is usually better for new projects ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [CTAN biblatex](https://ctan.org/pkg/biblatex)).
4. Myth: “XeLaTeX is always the modern default.” Reality: engine should be requirement-driven; LuaLaTeX often offers better modern pipeline ergonomics, while pdfLaTeX remains viable ([Overleaf compiler guide](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler%23Other_compilers), [CTAN fontspec](https://ctan.org/pkg/fontspec)).
5. Myth: “`minted` is just a prettier `listings` swap.” Reality: it adds external dependencies and shell-escape considerations ([CTAN minted](https://ctan.org/pkg/minted), [TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog)).
6. Myth: “`xparse` must be loaded for modern commands.” Reality: CTAN marks standalone `xparse` as obsolete because interfaces moved into kernel ([CTAN xparse](https://ctan.org/pkg/xparse)).
7. Myth: “LaTeX builds are inherently flaky.” Reality: deterministic build orchestration is standard with `latexmk` and CI root targeting ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [latex-action](https://github.com/xu-cheng/latex-action)).
8. Myth: “Table quality is subjective.” Reality: `booktabs` codifies strong typographic practice that consistently improves technical tables ([CTAN booktabs](https://ctan.org/pkg/booktabs)).
9. Myth: “One linter is enough.” Reality: TeX-structure lint and prose-style lint solve different failure modes ([CTAN chktex](https://ctan.org/pkg/chktex), [Vale docs](https://vale.sh/docs), [Textidote](https://github.com/sylvainhalle/textidote)).
10. Myth: “Cloud editors remove need for local build config.” Reality: even Overleaf supports project-level `latexmkrc`, and CI still needs explicit reproducible configuration ([Overleaf latexmkrc](https://docs.overleaf.com/managing-projects-and-files/the-latexmkrc-file), [latex-action](https://github.com/xu-cheng/latex-action)).
## 8) Case studies
### Case study 1: Modular technical report repo
Reference repo: [Scientific Thesis Template](https://github.com/latextemplates/scientific-thesis-template).
Observed choices:
- Multi-file chapter organization and bibliography separation (repo structure evidence in template tree).
- Build automation around standard TeX tooling.
Tradeoffs:
- Benefit: clearer ownership and lower merge conflict rates in chapter-scale collaboration.
- Cost: path/build orchestration complexity, especially when compiling from different working directories.
Recommendation derived from this pattern:
- Compile from canonical root with `latexmk -cd` or equivalent, standardize CI root file, and enforce local style packages for shared macros ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [latex-action](https://github.com/xu-cheng/latex-action)).
### Case study 2: Resume/CV repo with tailorable sections
Reference repos: [Awesome-CV](https://github.com/posquit0/Awesome-CV) and this workspace’s modular resume sources.
Observed choices:
- Tailorable section files (`experience`, `education`, `summary`) and reusable class/macros (`awesome-cv.cls` pattern).
- Separation between content fragments and presentation logic.
Tradeoffs:
- Benefit: fast per-role tailoring with low risk of global formatting regressions.
- Cost: macro-heavy classes can become opaque without conventions and lint/checks.
Recommendation derived from this pattern:
- Keep role-specific toggles/content in separate files, centralize visual rules in class/local style package, and use CI compile for each target variant ([CTAN hyperref](https://ctan.org/pkg/hyperref), [CTAN latexmk](https://ctan.org/pkg/latexmk), [pre-commit docs](https://pre-commit.com/)).
## 9) Final production checklist (printable)
- [ ] Engine decision documented (`pdfLaTeX` vs `LuaLaTeX`/`XeLaTeX`) with rationale.
- [ ] Preamble package order verified; `hyperref` compatibility constraints handled.
- [ ] File tree follows selected size pattern (small/medium/large).
- [ ] Reusable macros moved into local `.sty` package.
- [ ] Labels follow stable conventions (`sec:`, `fig:`, `tab:`, `eq:`).
- [ ] Bibliography stack chosen and pinned (`BibTeX` or `biblatex+biber`).
- [ ] Code listing policy chosen (`listings` default or `minted` with explicit security posture).
- [ ] Glossary/index build steps scripted if used.
- [ ] `latexmk` command standardized for local + CI.
- [ ] CI compiles canonical root file(s) on pull requests.
- [ ] TeX lint enabled (`chktex` minimum).
- [ ] Prose/style lint enabled (`Vale`/`Textidote`) where writing quality matters.
- [ ] Pre-commit hooks installed and documented.
- [ ] Shell-escape disabled by default; enabled only where required and reviewed.
- [ ] Build is reproducible from clean checkout.
Checklist references: [LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html), [latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [CTAN minted](https://ctan.org/pkg/minted), [TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog), [pre-commit docs](https://pre-commit.com/), [Vale docs](https://vale.sh/docs), [CTAN chktex](https://ctan.org/pkg/chktex).
---
## Three perspectives compared (required synthesis)
### 1) Minimalist core LaTeX
- Stack: class + minimal package set + BibTeX + Make/latexmk.
- Best for: short papers, conservative submission environments.
- Risks: slower migration to Unicode/font requirements and modern citation models.
- Evidence: baseline LaTeX/BibTeX semantics and conservative engine workflows ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [Overleaf compiler guide](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler%23Other_compilers)).
### 2) Modern developer tooling
- Stack: modular files + local `.sty` + `latexmk` + CI + lint + pre-commit.
- Best for: team docs, long-lived repositories, review-driven workflows.
- Risks: tooling setup overhead and occasional package/container drift.
- Evidence: orchestration/lint/CI tool docs ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [latex-action](https://github.com/xu-cheng/latex-action), [CTAN chktex](https://ctan.org/pkg/chktex), [pre-commit docs](https://pre-commit.com/)).
### 3) Template-driven approach
- Stack: template class (`.cls`) + predefined section structure + optional role/variant files.
- Best for: resumes/CVs and institutional outputs needing consistent branding.
- Risks: hidden complexity inside class files; lock-in to template assumptions.
- Evidence: template repositories and class-centric patterns ([Awesome-CV](https://github.com/posquit0/Awesome-CV), [Scientific Thesis Template](https://github.com/latextemplates/scientific-thesis-template)).
Opinionated synthesis:
- Start minimalist for speed.
- Shift to modern tooling once 2+ contributors or 20+ pages.
- Use template-driven architecture when output consistency is more important than maximal flexibility.