Installation and Setup

Prerequisites

This guide assumes a macOS system with Homebrew and Visual Studio Code already installed. The objective is to configure a local LaTeX environment for editing and previewing documents directly within VS Code.

Installing MacTeX

Installation via Homebrew

Install the MacTeX distribution using Homebrew. Note that recent versions of Homebrew have unified the install command for both formulae and casks.

brew install mactex

After installation, the package is typically located in a path like:

/usr/local/Caskroom/mactex/2024.xx.xx

Navigate to this directory and manually run the installer package (.pkg file). After installation, check your Applications folder for a TeX directory containing applications such as TeXShop and LaTeXiT. The presence of these applications confirms a successful LaTeX installation.

Configuring the System PATH

Verify the existence of the TeX directory within ~/Library. If it contains a texbin folder, add it to your system's PATH by editing your shell configuration file (e.g., ~/.zshrc).

export PATH="/Library/TeX/texbin:$PATH"

Reload your shell configuration or restart the terminal. Validate the installation by checking the versions of the LaTeX processors.

xelatex --version
pdflatex --version

Successful output from these commands indicates the LaTeX binaries are correctly accessible.

VS Code Configuration

Open VS Code and install the LaTeX Workshop extension. Restart the editor afterward.

Open the Command Palette (Cmd+Shift+P), search for "Preferences: Open User Settings (JSON)", and add the following configuration to your settings.json file.

{
    "latex-workshop.latex.autoBuild.run": "never",
    "latex-workshop.showContextMenu": true,
    "latex-workshop.intellisense.package.enabled": true,
    "latex-workshop.message.error.show": false,
    "latex-workshop.message.warning.show": false,
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOC%"
            ]
        },
        {
            "name": "pdflatex",
            "command": "pdflatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOC%"
            ]
        },
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOC%"
            ]
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
                "%DOCFILE%"
            ]
        }
    ],
    "latex-workshop.latex.recipes": [
        {
            "name": "XeLaTeX",
            "tools": ["xelatex"]
        },
        {
            "name": "PDFLaTeX",
            "tools": ["pdflatex"]
        },
        {
            "name": "BibTeX",
            "tools": ["bibtex"]
        },
        {
            "name": "LaTeXmk",
            "tools": ["latexmk"]
        },
        {
            "name": "XeLaTeX with BibTeX",
            "tools": ["xelatex", "bibtex", "xelatex", "xelatex"]
        },
        {
            "name": "PDFLaTeX with BibTeX",
            "tools": ["pdflatex", "bibtex", "pdflatex", "pdflatex"]
        }
    ],
    "latex-workshop.latex.clean.fileTypes": [
        "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind",
        "*.lof", "*.lot", "*.out", "*.toc", "*.acn",
        "*.acr", "*.alg", "*.glg", "*.glo", "*.gls",
        "*.ist", "*.fls", "*.log", "*.fdb_latexmk"
    ],
    "latex-workshop.latex.autoClean.run": "onFailed",
    "latex-workshop.latex.recipe.default": "lastUsed",
    "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click"
}

Save the file and restart VS Code to apply the new settings.

Writing and Compiling a LaTeX Document

Create a new file named test.tex and add the following content to verify the setup.

\documentclass{article}
\usepackage{amsmath}

\title{Example LaTeX Document}
\author{Author Name}
\date{\today}

\begin{document}
\maketitle

\section{Introduction}
This is a basic document demonstrating LaTeX typesetting capabilities.

\section{Mathematical Typesetting}
LaTeX is renowned for its high-quality mathematical output. The quadratic formula is presented below.

\begin{equation}
  y = \frac{ -p \pm \sqrt{p^2 - 4q} }{ 2 }
\end{equation}

\end{document}

To compile the document, click the green triangle ("Build LaTeX project") icon in the top-right corner of the editor. After a successful build, click the PDF preview icon (usually to the right of the build icon) to view the generated document. The LaTeX Workshop sidebar provides additional tools and compilation logs. The status bar at the bottom of the VS Code window displays the build progress, and the "Output" panel shows detailed logs. A message indicating Process finished with exit code 0 signifies a successful compilation.

Recommended Resources

Online LaTeX Editors

• Overleaf: A popular web-based LaTeX editor for collaborative work. https://www.overleaf.com/
• Overleaf Resume Templates: A collection of CV and resume templates. https://www.overleaf.com/latex/templates/tagged/cv

Useful Tools

• LaTeX Equation Editor: A web tool for visually composing and previewing equations. https://latex.codecogs.com/eqneditor/editor.php