The LaTeX Headaches You’re Likely to Run Into

A few practical LaTeX pitfalls

LaTeX is extremely capable, but using it smoothly often depends on avoiding a handful of recurring issues. Most trouble comes from encoding, file paths, compilation leftovers, and template setup rather than from writing the document itself.

Editors and tools worth keeping in mind

Online options

• Online LaTeX formula editors are useful when you just want to type and preview equations quickly.
• Overleaf is a web-based LaTeX editor with real-time collaboration, which makes it convenient for shared projects.

Local tools

• MiKTeX is a LaTeX distribution commonly used on Windows, and its automatic package updates are especially convenient.
• AxSoft is a paid tool for equation editing and diagram creation.

VS Code extensions

• LaTeX Workshop adds syntax highlighting, auto-completion, and other LaTeX-focused features to VS Code.
• Overleaf-Workshop lets you open Overleaf or ShareLaTeX projects inside VS Code while keeping collaborative workflows intact.

Learning and template resources

If you are still getting comfortable with LaTeX, an interactive beginner course built around Overleaf can help shorten the learning curve.

For document structure, starting from an existing template is usually better than building everything from scratch. Common template collections include material for theses, presentations, reports, and resumes. A resume template such as Awesome-CV is also a popular option.

Problems that show up often

Chinese encoding issues

When using the CJK package, GBK encoding may be required. If the preamble includes Chinese text references—for example, Chinese content used in headers or footers—you also need to add the necessary tags there.

Equation environments and numbered line breaks

Equation layout and line breaking with numbering can be a source of confusion in LaTeX. This is one of those areas where checking a dedicated guide on formula writing is often more efficient than guessing your way through the environment rules.

File path limitations

One rule is easy to overlook but important: the directory containing your LaTeX files should use English-only paths. Avoid Chinese characters in folder names, since they can lead to compilation problems.

Compilation failures caused by leftover files

A failed build is not always caused by the .tex source itself. Auxiliary files left behind after previous compilations can break later runs.

A typical fix is to clean generated files before compiling again, especially files such as:

• .aux
• .log
• .out

You can do this manually, use your editor’s cleanup function, or rely on an automated build tool such as latexmk to manage intermediate files for you.

Template compilation errors

If a template refuses to compile, the first thing to check is whether all required packages are installed. In many cases, MiKTeX can install missing packages automatically as long as the network connection is working.

It is also worth checking whether the template expects a LaTeX distribution version that matches your current environment.

How LaTeX compilation is typically organized

Understanding the file roles can make troubleshooting much easier.

Files that can be compiled or used in the build process

• .dtx — a combined code-and-documentation format that can be compiled into package documentation
• .tex — the normal document source compiled directly
• .ins — used with docstrip to split a .dtx file into files such as .cls, .sty, .bbx, .cbx, and .bst

Bibliography-related style files

• .bbx, .cbx, .bst — bibliography style files; these are often listed separately instead of being bundled into the .dtx structure

A common compilation flow

1. Generate the template files first: use .ins to produce the files extracted from .dtx.
2. Compile the document with a LaTeX engine: depending on the setup, you can use recipes based on engines such as xelatex or lualatex.
3. Automate the process when possible: build recipes are often managed by helper tools. - Many projects use build.lua - latexmk uses latexmkrc - GNU Make uses Makefile

A representative example of a full thesis template is thuthesis, a LaTeX thesis template associated with Tsinghua University.

About embedding LaTeX in Markdown

Mixing Markdown with LaTeX is a common workflow, but it introduces another layer of tooling and syntax expectations. If you go this route, it helps to be clear about which parts are handled by the Markdown processor and which are passed through to the LaTeX engine.

Habits that make LaTeX projects easier to manage

A few practices reduce the chances of painful breakage later:

1. Use version control — Git is a good fit for tracking document changes.
2. Back up important files regularly — especially before major compilation or template changes.
3. Start from a trustworthy template — it is usually more efficient than assembling everything from zero.
4. Keep your distribution and packages updated — many odd errors come from outdated environments.
5. Read the package documentation first when something breaks — package docs are often the fastest path to the real answer.

LaTeX rewards careful setup. Once encoding, paths, templates, and compilation tools are under control, the experience becomes much more stable and predictable.