VS Code (LaTeX Workshop)

Ajoutez l'extension LaTeX Workshop à Visual Studio Code et un éditeur de code à usage général devient un environnement LaTeX sérieux : il compile à chaque sauvegarde, affiche le PDF dans un onglet côte à côte et vous permet de passer de la source à PDF dans les deux sens. Cette page présente la configuration, le fonctionnement des builds (recettes et outils) et l'intégration de SyncTeX.

Qu'est-ce que LaTeX Workshop

VS Code ne compose pas lui-même TeX. La compilation proprement dite est effectuée par une distribution que vous installez sur votre machine — TeX Live (ou MiKTeX / MacTeX). LaTeX Workshop, de James Yu, est le pont entre l'éditeur et cette distribution : il lance les builds, prévisualise le PDF et ajoute la complétion, la coloration syntaxique, le passage à la définition pour \ref/\cite, une vue schématique, et plus encore. Son Marketplace ID est James-Yu.latex-workshop, avec plus de 5 millions d'installations — en fait l'extension LaTeX par défaut dans l'écosystème VS Code.

La seule condition préalable est que les commandes TeX soient accessibles sur votre PATH. L'extension génère simplement des exécutables tels que latexmk ou pdflatex en tant que processus enfants, donc si latexmk --version fonctionne dans un terminal, l'extension fonctionnera presque certainement aussi. A l'inverse, le choix d'un moteur ou la configuration des polices japonaises est une affaire de distribution, pas d'extension.

Compilez d'abord une fois dans le terminal

Avant de régler les paramètres de VS Code, créez le même projet une fois dans un terminal. Si latexmk ne peut pas s'y exécuter, LaTeX Workshop ne peut pas non plus le lancer. Pour un premier document, essayez l'un de ceux-ci depuis le dossier du projet :

latexmk -pdf main.tex
# 日本語 upLaTeX を .latexmkrc に書いた場合 / if .latexmkrc selects upLaTeX
latexmk main.tex

Une fois les erreurs PATH et de paquet manquant résolues, tout échec côté VS Code est limité aux recettes, à la détection du fichier racine ou à la visionneuse PDF. Si la construction du terminal fonctionne mais que l'extension échoue, inspectez settings.json : le répertoire de sortie, le nom de la recette et les espaces réservés sont les suspects habituels.

Configuration

Les étapes sont simples. Installez VS Code, installez une distribution telle que TeX Live (en 2026, TeX Live 2026) et assurez-vous qu'elle est sur votre PATH. Ensuite, ouvrez la vue Extensions (Ctrl/Cmd+Shift+X), recherchez « LaTeX Workshop » et installez-la. Juste après avoir modifié le PATH, redémarrez VS Code – idéalement l'intégralité du OS – pour que le nouvel environnement soit récupéré. Ouvrez un fichier .tex et l'icône de la barre d'activité TeX sur la gauche vous donne les commandes de construction et d'aperçu.

Settings vit dans settings.json (à partir du Ctrl/Cmd+, Settings UI, utilisez « Ouvrir Settings (JSON) » en haut à droite ; vous pouvez modifier soit le fichier utilisateur global, soit un .vscode/settings.json par projet). Les trois clés à connaître en premier sont :

• latex-workshop.latex.outDir — où vont les fichiers intermédiaires et le PDF. %DIR% par défaut (à côté du .tex). Le régler par ex. out garde votre dossier source épuré.
• latex-workshop.latex.autoBuild.run — ce qui déclenche une construction automatique : onFileChange (par défaut ; surveille les dépendances), onSave (lors de la sauvegarde) ou never (manuel uniquement). Si vous souhaitez un comportement prévisible, onSave est un choix sûr.
• latex-workshop.view.pdf.viewer — où PDF apparaît : tab (par défaut ; un onglet à l'intérieur de VS Code), browser ou external. Pour le SyncTeX sans friction, le tab est le meilleur choix.

Un point de départ minimal est simplement ceci : collecter la sortie dans out/, construire sur la sauvegarde et afficher le PDF dans l'onglet intégré :

{
  "latex-workshop.latex.outDir": "%DIR%/out",
  "latex-workshop.latex.autoBuild.run": "onSave",
  "latex-workshop.view.pdf.viewer": "tab"
}

%DIR% est un espace réservé qui s'étend jusqu'au répertoire du fichier racine en cours de traitement ; il réapparaît dans les recettes ci-dessous. Après une build, l'extension peut également ranger ou conserver les fichiers intermédiaires (.aux, .log, …) via latex-workshop.latex.autoClean.run, mais régler le répertoire de sortie et le déclencheur suffit pour s'en faire une idée.

Créer des recettes et des outils

Les builds dans LaTeX Workshop ont deux couches : « outils » et « recettes ». Un outil (latex-workshop.latex.tools) définit une seule commande à exécuter : name, command (l'exécutable) et args. Une recette (latex-workshop.latex.recipes) est une séquence ordonnée d'outils, avec un tableau name et un tableau tools répertoriant les noms d'outils. Un flux tel que « pdflatex → bibtex → pdflatex → pdflatex » — exécution de la passe bibliographique puis réexécution — est exprimé comme une seule recette.

Sans configuration, l'extension utilise ses recettes par défaut intégrées. Le premier est un seul latexmk, et c'est la valeur par défaut prévue (lorsque latex-workshop.latex.recipe.default est "first", la première recette de la liste est choisie ; réglez-la sur "lastUsed" pour mémoriser la recette que vous avez choisie en dernier). Étant donné que latexmk inspecte les dépendances et réexécute exactement autant de fois que nécessaire, vous n'avez jamais besoin de compter les passages pour les références croisées, la table des matières ou la bibliographie. L'outil latexmk par défaut est défini à peu près comme ceci :

{
  "name": "latexmk",
  "command": "latexmk",
  "args": [
    "-synctex=1",
    "-interaction=nonstopmode",
    "-file-line-error",
    "-pdf",
    "-outdir=%OUTDIR%",
    "%DOC%"
  ],
  "env": {}
}

Lecture des arguments : -synctex=1 émet les données SyncTeX discutées ci-dessous ; -interaction=nonstopmode s'exécute directement au lieu de s'arrêter pour saisir une erreur ; -file-line-error affiche les erreurs sous la forme « file:line: message », ce qui facilite le passage à l'endroit incriminé. -pdf indique à latexmk de produire PDF directement via pdfLaTeX. %OUTDIR% s'étend à votre outDir et %DOC% au chemin du fichier racine sans son extension (les autres espaces réservés incluent %DOCFILE% = nom de fichier sans extension et %DIR% = le répertoire racine).

Les recettes par défaut incluent également les variantes de moteur latexmk (lualatex) et latexmk (xelatex), ainsi que latexmk (latexmkrc), qui exécute latexmk %DOC% sans arguments supplémentaires et reporte tout à un .latexmkrc. Pour les Japonais, cette approche « mettre tout dans .latexmkrc » est la plus propre. Déposez un .latexmkrc à la racine du projet et nommez le moteur et le convertisseur. Voici une configuration upLaTeX + dvipdfmx — la combinaison classique pour les articles japonais en sciences :

$latex = 'uplatex -synctex=1 -interaction=nonstopmode -file-line-error %O %S';
$bibtex = 'upbibtex %O %B';
$biber = 'biber --bblencoding=utf8 -u -U --output_safechars %O %S';
$makeindex = 'upmendex %O -o %D %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;
$max_repeat = 5;

Essentiellement, vous attribuez uplatex à $latex, dvipdfmx à $dvipdf et configurez $pdf_mode = 3 pour choisir le chemin « construire un DVI, puis le convertir en PDF avec dvipdfmx » ($pdf_mode = 1 est directement pdfLaTeX, 4 est LuaLaTeX). L'index passe par upmendex et la bibliographie par upbibtex, qui gère bien le japonais. %S, %O et %D sont les espaces réservés de latexmk pour la source, les options et le fichier de sortie. Désormais, du côté de VS Code, vous choisissez simplement la recette latexmk (latexmkrc) et n'encodez jamais le choix du moteur dans settings.json.

Si vous préférez tout conserver dans settings.json sans .latexmkrc, définissez votre propre outil et votre propre recette et mettez la recette japonaise en premier. Voici un exemple autonome de composition du japonais avec LuaLaTeX (qui définit le japonais via luatexja/ltjsclasses, ne nécessitant ni .latexmkrc ni dvipdfmx) :

{
  "latex-workshop.latex.tools": [
    {
      "name": "lualatexmk",
      "command": "latexmk",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-lualatex",
        "-outdir=%OUTDIR%",
        "%DOC%"
      ],
      "env": {}
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "lualatexmk",
      "tools": ["lualatexmk"]
    }
  ],
  "latex-workshop.latex.outDir": "%DIR%/out",
  "latex-workshop.latex.autoBuild.run": "onSave"
}

Vous pouvez également mettre des commentaires magiques comme % !TEX program = ... ou % !TEX root = ... en haut d'un fichier, et LaTeX Workshop les honore (désactivé via latex-workshop.latex.build.enableMagicComments). Le système de recettes est la voie recommandée aujourd'hui ; % !TEX root gagne sa place dans les projets multi-fichiers, lorsque vous souhaitez compiler le document principal tout en éditant un sous-fichier inclus.

Épingler le fichier racine

Dans un projet multi-fichiers, si LaTeX Workshop se trompe, il peut essayer de compiler directement le fichier enfant que vous éditez. L'extension déduit la racine en recherchant les relations \documentclass, \begin{document} et \input/\include, mais pour les projets de la taille d'une thèse comportant de nombreux fichiers de chapitres, la direction explicite est plus stable.

% !TEX root = ../main.tex

\section{実験方法}
この章だけを編集中でも、ビルドは main.tex から始めます。

• Placez % !TEX root = ... en haut des fichiers enfants pour que le fichier d'entrée soit explicite.
• Ouvrez l'espace de travail à la racine du projet contenant main.tex, et non dans un dossier de chapitre isolé.
• La sélection manuelle des recettes peut remplacer les commentaires magiques, alors gardez le nom de la recette quotidienne cohérent au sein de l'équipe.
• Si la sélection racine continue de vous demander, épinglez la stratégie dans le fichier .vscode/settings.json du projet.

intégration SyncTeX

SyncTeX enregistre la correspondance entre les lignes source et les positions dans le PDF (le -synctex=1 ci-dessus écrit ce mappage dans un .synctex.gz). Il vous permet de synchroniser votre point d'écriture et la vue PDF, dans les deux sens. L'utilisation de la visionneuse PDF intégrée (viewer défini sur tab) est le chemin le plus fluide et sans configuration.

Recherche avant (source → PDF) passe de votre position d'édition à l'endroit correspondant dans le PDF. Le raccourci est Ctrl+Alt+J (sur Mac, Cmd+Option+J) ; dans la palette de commandes, il s'agit de « LaTeX Workshop : SyncTeX from cursor ». Pour exécuter automatiquement la recherche directe juste après une génération, définissez latex-workshop.synctex.afterBuild.enabled sur true.

La recherche inverse (PDF → source) va dans l'autre sens, depuis un endroit dans le PDF jusqu'à la ligne source correspondante. Dans la visionneuse d'onglets intégrée, Ctrl-cliquez (Cmd-cliquez sur Mac) dans PDF déplace le curseur sur cette ligne. Le style de clic est défini par latex-workshop.view.pdf.internal.synctex.keybinding, soit ctrl-click (par défaut) ou double-click. Apprenez ensemble la paire avant/arrière et vous pourrez accéder instantanément au bon endroit, même dans un long document.

Pour SyncTeX en japonais, deux choses suffisent : passer -synctex=1 à $latex dans votre .latexmkrc (déjà fait dans l'exemple ci-dessus), et sachez que même via DVI ($pdf_mode = 3), upLaTeX + dvipdfmx transporte les données SyncTeX. SyncTeX avec une visionneuse externe (latex-workshop.view.pdf.external.synctex.*) nécessite plus de configuration, l'onglet intégré est donc l'endroit recommandé pour commencer.