### Quickstart Development Setup

Source: https://github.com/james-yu/latex-workshop/blob/master/CONTRIBUTING.md

Clones the repository, sets up pre-commit hooks, installs dependencies, and opens the project in VS Code.

```bash
git clone https://github.com/James-Yu/LaTeX-Workshop.git
cd ./LaTeX-Workshop
cp ./dev/githooks/pre-commit .git/hooks/
npm ci
code -n .
```

--------------------------------

### Install Node Modules

Source: https://github.com/james-yu/latex-workshop/blob/master/CONTRIBUTING.md

Installs the necessary node modules for building the extension.

```bash
npm ci
```

--------------------------------

### Example EnvironmentRaw object

Source: https://github.com/james-yu/latex-workshop/blob/master/dev/README.md

An example of an EnvironmentRaw object.

```json
{
  "name": "acronym",
  "arg": {
    "format": "[]",
    "snippet": "acronym[${1:longest}]"
  }
}
```

--------------------------------

### Promote Sectioning Example

Source: https://github.com/james-yu/latex-workshop/wiki/Snippets

Example demonstrating the effect of the `latex-workshop.promote-sectioning` command on sectioning levels.

```latex
\subsection{Demo}
\paragraph{Content}
```

```latex
\section{Demo}
\subsubsection{Content}
```

--------------------------------

### Customizing Color Theme for Math Environment

Source: https://github.com/james-yu/latex-workshop/wiki/FAQ

Example JSON configuration to make fonts black in math environments.

```json
    "editor.tokenColorCustomizations": {
        "textMateRules": [
            {
                "scope": [
                    "support.class.math.block.environment.latex",
                ],
                "settings": {
                    "foreground": "#000000"
                }
            }
        ]
    }
```

--------------------------------

### Texify Toolchain Configuration

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

Example configuration for using the 'texify' toolchain in LaTeX Workshop, demonstrating how to set up recipes and tool arguments.

```json
"latex-workshop.latex.recipes": [{
  "name": "texify",
  "tools": [
    "texify"
  ]
}],
"latex-workshop.latex.tools": [{
  "name": "texify",
  "command": "texify",
  "args": [
    "--synctex",
    "--pdf",
    "--tex-option=\"-interaction=nonstopmode\"",
    "--tex-option=\"-file-line-error\"",
    "%DOC_EXT%"
  ],
  "env": {}
}]
```

--------------------------------

### Example MacroRaw object

Source: https://github.com/james-yu/latex-workshop/blob/master/dev/README.md

An example of a MacroRaw object.

```json
{
  "name": "DeclareAcronym",
  "arg": {
    "format": "{}{}",
    "snippet": "DeclareAcronym{${1:id}}{${2:properties%keyvals}}",
    "keys": [
      "\\DeclareAcronym#c,..."
    ],
    "keyPos": 1
  }
}
```

--------------------------------

### Example % !TEX options in .tex file

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

This example demonstrates how to define the arguments for the `% !TEX program` magic comment directly within the .tex file using the `% !TEX options` directive.

```latex
% !TEX options = -synctex=1 -interaction=nonstopmode -file-line-error "%DOC%"
```

--------------------------------

### External PDF Viewer Command

Source: https://github.com/james-yu/latex-workshop/wiki/View

Example of setting the command to execute for an external PDF viewer.

```json
    "latex-workshop.view.pdf.external.viewer.command": "/usr/bin/okular",
```

--------------------------------

### Custom AT Suggestions

Source: https://github.com/james-yu/latex-workshop/wiki/Intellisense

Example of how to add, replace, or remove default AT suggestions. The key is the triggering string (must start with '@'), and the value is the snippet to be inserted. An empty string removes the snippet.

```json
{ "@.": "\\cdot", "@6": "" }
```

--------------------------------

### External PDF Viewer Arguments

Source: https://github.com/james-yu/latex-workshop/wiki/View

Example of providing arguments to an external PDF viewer.

```json
   "latex-workshop.view.pdf.external.viewer.args": [
        "--unique",
        "%PDF%"
    ],
```

--------------------------------

### Example % !BIB options in .tex file

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

This example demonstrates how to define the arguments for the `% !BIB program` magic comment directly within the .tex file using the `% !BIB options` directive.

```latex
% !BIB options = "%DOCFILE%"
```

--------------------------------

### Environment Variable Example: TEXMFHOME

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

Example of how to set the TEXMFHOME environment variable to point to a local texmf subdirectory within a project.

```json
"env": {
    "TEXMFHOME": "%DIR%/texmf"
  }
```

--------------------------------

### Default LaTeX Recipes Configuration

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

Example JSON configuration for defining LaTeX recipes, which are sequences of commands executed during the build process. This shows a recipe using 'latexmk' and another using a sequence of 'pdflatex' and 'bibtex'.

```json
"latex-workshop.latex.recipes": [
  {
    "name": "latexmk",
    "tools": [
      "latexmk"
    ]
  },
  {
    "name": "pdflatex -> bibtex -> pdflatex\u200b*\u200b2",
    "tools": [
      "pdflatex",
      "bibtex",
      "pdflatex",
      "pdflatex"
    ]
  }
]
```

--------------------------------

### Evince Configuration (Linux)

Source: https://github.com/james-yu/latex-workshop/wiki/View

Configuration for Evince on Linux to work with VS Code for SyncTeX.

```json
{
    "latex-workshop.view.pdf.viewer": "external",
    "latex-workshop.view.pdf.external.viewer.command": "evince2",
    "latex-workshop.view.pdf.external.viewer.args": [
        "%PDF%"
    ],
    "latex-workshop.view.pdf.external.synctex.command": "evince_forward_search",
    "latex-workshop.view.pdf.external.synctex.args": [
        "%PDF%",
        "%LINE%",
        "%TEX%"
    ]
}
```

--------------------------------

### VS Code Launch Configuration for Running Tests

Source: https://github.com/james-yu/latex-workshop/blob/master/test/README.md

This configuration in `.vscode/launch.json` is used to launch VS Code with specific arguments and environment variables for running tests.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/vscode/bin/test",
      "args": [
        "--run-in",
        "${workspaceFolder}/test/fixtures/testground",
        "--grep",
        "test/fixtures/testground"
      ],
      "env": {
        "LATEXWORKSHOP_SUITE": ""
      }
    }
  ]
}
```

--------------------------------

### Run Tests

Source: https://github.com/james-yu/latex-workshop/blob/master/CONTRIBUTING.md

Runs all tests for the extension.

```bash
npm run test
```

--------------------------------

### Build Release Image

Source: https://github.com/james-yu/latex-workshop/blob/master/CONTRIBUTING.md

Builds a release image of the extension.

```bash
npm run release
```

--------------------------------

### GitHub Codespaces Architecture

Source: https://github.com/james-yu/latex-workshop/blob/master/viewer/README.md

Flowchart illustrating the architecture when using GitHub Codespaces.

```mermaid
flowchart TB
  subgraph Remote["Remote machine"]
    subgraph ExtensionHost["VS Code Server (Extension Host)"]
      LW["LaTeX Workshop"]
      Server["Server for PDF viewer\n(Files and WebSocket)\n127.0.0.1 at remote"]
      LW --- Server
    end
    PortForwarder
  end
  GitHub["github.dev"]
  GitHubPreview["githubpreview.dev"]
  subgraph Browser
    subgraph WebView["parent iframe"]
      PDFViewer["PDF viewer (viewer.html)"]
    end
  end
  ExtensionHost <--> GitHub
  Server <--> PortForwarder
  PortForwarder <--> GitHubPreview
  GitHub <--> Browser
  GitHubPreview <--> PDFViewer
```

--------------------------------

### Caddy Reverse Proxy Configuration

Source: https://github.com/james-yu/latex-workshop/wiki/Remote

Example configuration for Caddy to forward requests to the LaTeX Workshop PDF server when running VS Code as a web server.

```plaintext
yourdomain.com {
    handle_path /latex-workshop-pdf/* {
        reverse_proxy 127.0.0.1:34567
    }
    # ... your existing code serve-web rule
}
```

--------------------------------

### WSL: Executable Extension for Windows TeX Binaries

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

On Windows Subsystem for Linux (WSL), when calling TeX executables installed on the Windows file system, the `.exe` extension must be added to the command.

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

--------------------------------

### check-config.py

Source: https://github.com/james-yu/latex-workshop/wiki/README

A script to check configuration variables between the wiki and the LaTeX-Workshop project.

```python
check-config.py
```

--------------------------------

### latex-workshop.latex.external.build.args Configuration

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

Arguments for the external build command.

```json
"latex-workshop.latex.external.build.args": []
```

--------------------------------

### latex-workshop.latex.clean.args Configuration

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

Arguments for the clean command.

```json
"latex-workshop.latex.clean.args": ["-outdir=%OUTDIR%", "-c", "%TEX%"]
```

--------------------------------

### build-grammar.js script

Source: https://github.com/james-yu/latex-workshop/blob/master/dev/README.md

This script generates .json grammar files from .yaml files.

```javascript
node build-grammar.js
```

--------------------------------

### Configuration for Subfile Handling

Source: https://github.com/james-yu/latex-workshop/wiki/Compile

Configuration options related to the 'subfiles' package, determining whether to use the main file or the subfile for IntelliSense and non-interactive commands, and whether to prompt the user.

```json
{
  "latex-workshop.latex.rootFile.useSubFile": true,
  "latex-workshop.latex.rootFile.doNotPrompt": false
}
```

--------------------------------

### Compile Extension

Source: https://github.com/james-yu/latex-workshop/blob/master/CONTRIBUTING.md

Compiles the extension.

```bash
npm run compile
```

--------------------------------

### tex-fmt arguments

Source: https://github.com/james-yu/latex-workshop/wiki/Format

Configuration for command line arguments for tex-fmt.

```json
["--nowrap"]
```

--------------------------------

### qpdfview support

Source: https://github.com/james-yu/latex-workshop/wiki/View

Configuration for qpdfview PDF viewer with Synctex support.

```json
"latex-workshop.view.pdf.viewer":"external",
"latex-workshop.view.pdf.external.viewer.command": "qpdfview",
"latex-workshop.view.pdf.external.viewer.args": [
    "--unique",
    "%PDF%"
],
"latex-workshop.view.pdf.external.synctex.command": "qpdfview",
"latex-workshop.view.pdf.external.synctex.args": [
    "--unique",
    "%PDF%#src:%TEX%:%LINE%:0",
],
```

--------------------------------

### Sioyek Configuration

Source: https://github.com/james-yu/latex-workshop/wiki/View

Configuration for Sioyek to work with VS Code for inverse and forward search.

```json
{
    "latex-workshop.view.pdf.external.viewer.command": "C:\\path\\to\\sioyek\\sioyek.exe",
    "latex-workshop.view.pdf.external.synctex.command": "C:\\path\\to\\sioyek\\sioyek.exe",
    "latex-workshop.view.pdf.external.synctex.args": [
        "--inverse-search",
        "\"C:\\path\\to\\vscode\\Code.exe\" \"C:\\path\\to\\vscode\\resources\\app\\out\\cli.js\" --ms-enable-electron-run-as-node -r -g \"%1:%2\"",
        "--reuse-instance",
        "--forward-search-file",
        "%TEX%",
        "--forward-search-line",
        "%LINE%",
        "%PDF%"
    ]
}
```

--------------------------------

### Opening a PDF file

Source: https://github.com/james-yu/latex-workshop/blob/master/viewer/README.md

Sequence diagram illustrating the process of opening a PDF file in the viewer.

```mermaid
sequenceDiagram
  participant Viewer as PDF Viewer
  participant Server as WebSocket Server
  participant WebServer as Web Server
  Note over Viewer: load viewer.html
  Note over Viewer: load latexworkshop.js
  Viewer-)Server: open
  Viewer->>WebServer: fetch /config.json
  Note over Viewer: load viewer.js
  Note over Viewer: webviewerloaded
  Viewer->>Viewer: Set PDFViewerApplicationOptions
  Note over Viewer: pagesinit
  Note over Viewer: documentloaded
  Viewer->>Viewer: Apply params
  Note over Viewer: pagesloaded
  Viewer-)Server: loaded
```