| name | latex-compile |
| description | Use when compiling LaTeX documents with XeLaTeX, or encountering compilation errors, missing cross-references, or diagnostic warnings. |
LaTeX Compile
LaTeX compilation assistant for XeLaTeX projects, handling compilation errors, cross-references, and diagnostics.
Overview
This skill provides the standard XeLaTeX compilation workflow for LaTeX projects, including error diagnosis and fixes.
Important: When users invoke this skill, they typically have compilation problems that need solving. Always display sufficient error information for diagnosis — do not over-filter the output!
When to Use
Use when:
- Compiling
.tex files with XeLaTeX
- Encountering LaTeX compilation errors (environment mismatch, undefined references, Chinese character issues)
- Diagnosing compilation warnings or failed builds
Don't use when:
- Compiling with pdfLaTeX or LuaLaTeX (commands differ)
- Setting up a new LaTeX project from scratch (use latex-textbook-writer templates instead)
Standard Compilation Commands
VSCode LaTeX Workshop recipe (XeLaTeX):
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex
Parameters:
-synctex=1: Generate SyncTeX data for PDF viewer synchronization-interaction=nonstopmode: Continue compilation on errors (shows all errors at once)-file-line-error: Display error messages with file and line numbersmain.tex: Main LaTeX file
Compilation passes:
- Must compile twice: First pass generates
.aux files, second pass updates cross-references
- If labels or references change, compile again
Common Compilation Error Diagnosis
1. Environment Mismatch Error
Symptom:
! LaTeX Error: \begin{document} ended by \end{remark}.
Cause: Mismatched environment begin/end tags
Diagnosis command:
grep -n "begin{remark}\|end{remark}" chapters/*.tex
Fix:
- Check each
\begin{remark} has corresponding \end{remark}
- Remove extra
\end{remark} tags
2. Missing Required Parameter Error
Symptom:
! Package pgfkeys Error: I do not know the key '/tcb/Title'...
Cause: Incorrect theorem environment format
Correct format:
% CORRECT format (using \newtcbtheorem)
\begin{remark}{Title}{label}
Content...
\end{remark}
% WRONG format
\begin{remark}[Title]
Content...
\end{remark}
3. Chinese Character Error
Symptom:
! Package pgfkeys Error: I do not know the key '/tcb/中文标题'...
Cause: Chinese title in square brackets
Fix: Ensure using {Title}{label} format
4. Undefined Reference Warning
Symptom:
LaTeX Warning: Reference `eq:label' undefined...
LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.
Fix: Run compilation again (second pass)
Compilation Output Interpretation
Successful compilation
Output written on main.pdf (93 pages).
Transcript written on main.log.
Warnings but successful
Package hyperref Warning: Token not allowed in a PDF string (Unicode)...
Output written on main.pdf (93 pages).
- hyperref warnings are usually ignorable (Unicode in PDF bookmarks)
Failed compilation
! LaTeX Error: ...
l.123 \begin{remark}
- Line number indicates error location
- Must fix error before recompiling
Quick Diagnosis Commands
⚠️ Important: When diagnosing compilation errors, do not over-filter the output! Error information may be anywhere in the output. Using head or tail may miss critical errors.
Recommended Error Diagnosis Methods
Method 1: Show all errors and warnings (recommended)
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex 2>&1 | grep -E "Error|! |Warning"
This displays all errors, warnings, and fatal errors starting with !.
Method 2: Limit line count but don't use head/tail
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex 2>&1 | grep -E "Error|! " | head -50
If the output is truly too large, you can use head -50 to limit to the first 50 errors, but never use tail!
Method 3: Check specific types of errors
grep -E "begin|end" main.tex | grep -v "%"
grep -n "begin{remark}\|end{remark}" chapters/*.tex
Not Recommended (will miss errors)
❌ Don't do this:
xelatex ... 2>&1 | tail -10
xelatex ... 2>&1 | head -30
xelatex ... 2>&1 | tail -20
Other Useful Diagnostic Commands
View specific line range:
sed -n '1500,1550p' chapters/chapter02.tex
Check specific labels:
grep -n "label{eq:" chapters/*.tex | sort | uniq -d
Compilation Workflow
⚠️ Important Principle: When users invoke this skill, they have compilation problems. Must display sufficient error information to help diagnose!
Step 1: Get Complete Error Information
Recommended approach: Show all errors without using head/tail
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex 2>&1 | grep -E "Error|! "
If output is truly too large (over 100 lines), you can limit the count:
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex 2>&1 | grep -E "Error|! " | head -50
❌ Never use tail to view errors:
xelatex ... 2>&1 | tail -10
Step 2: Diagnose Problems Based on Error Messages
After viewing error messages, locate the specific file and line number:
- Error format:
./filename.tex:line_number: error_description
- Use Read tool to view content around that line
Step 3: Fix Errors and Recompile
After fixing errors, recompile to verify:
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex
Standard Two-Pass Compilation (only after first pass succeeds)
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex && \
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex
Common Issues
Q: PDF not updated?
A: Delete .aux and .synctex.gz files and recompile:
rm -f *.aux *.synctex.gz *.log
xelatex -synctex=1 -interaction=nonstopmode -file-line-error main.tex
Q: VSCode compiles successfully, but command line fails?
A: Check VSCode LaTeX Workshop settings to ensure same compilation command
Q: Compilation is slow?
A: This is normal, XeLaTeX compiling large documents takes time. First compilation is usually slower.
File Dependencies
Compilation requires:
main.tex (main file)chapters/*.tex (chapter files)figures/ (image files, if any).cls or .sty files (if using custom class)
References
