VSCode Settings

Note

If you intend to use our Docker image, then please follow the configuration and introduction documentation first.

Note

If you would not like to use docker, but still vscode, then just install the following extensions for the best LaTeX experience:

• LaTeX Workshop

• LaTeX Highlighting and Grammar

• Spelling

Prerequisites

Note

Required for Docker + VSCode only

Software

• VSCode

• Docker

(Installation instructions can be found here)

VSCode Extension

Start VSCode and install the needed Remote Containers extension.

Develop inside a container

Warning

We recommend to chose a specific tag at all times instead of latest. However, you will see latest in the documentation, just replace it with any version tag of the BFH CI releases, starting from 1.5.2.

Note

The VSCode image contains all BFH templates, examples, logos and fonst installed in the default TEXMFHOME directory, which is normally /home/vscode/texmf/ find it running

$ kpsewhich -var-value=TEXMFHOME

inside the container. So there is no need to download them manually if you follow the steps described below.

1. Docker image configuration

   For each project you would like to edit in VSCode, using our LaTeX Docker image, you have to specify a project specific configuration file.

   It immediately provides the following benefits:

   • You will always know which exact version of the BFH CI you have used for each project

   • You will always have the required dependencies documented and installed

   This file must be called .devcontainer.json and must be located in the top level directory of your project. For a complete list of possible options please read here. For a simple guide on how to install addtitional LaTeX packages see here.

   Example:

   {
      "name": "BFH LaTeX CI",
      "image": "registry.gitlab.ti.bfh.ch/bfh-latex/registry/vscode:latest",
   
      "customizations": {
         "vscode": {
            "extensions": [
                "james-yu.latex-workshop",
                "ban.spellright",
                "valentjn.vscode-ltex"
            ],
         }
      },
   
      "remoteUser": "vscode"
   }
   

   Warning

   The configuration above might not work out of the box with the extension. As the extension does not default to build with lualatex which is required for the bfh template. Instead we recommend to use the configuration which can be downloaded here: .devcontainer.json. This devcontainer configuration makes sure the latex workshop extension only provides build features with lualatex.

   Note

   This file must be located in each LaTeX project directory you will be working in. VSCode takes the image specified under image and installs other extensions specified under extensions into the container. Feel free to add other desired extensions.

   Replace the latest tag (found in image) with a specific version

2. Open the project directory containing the .devcontainer.json in VSCode (File->Open Folder)

   VSCode should recognize the .devcontainer.json file and automatically prepare the system using the steps described below:

   • VSCode will download the specified image if it has not already been downloaded. (This may take a while)

   • It installs the specified extensions.

   After the VSCode image is successfully created, you should see the launched container. Similar to the figure below.

   

3. Copy the desired template / example to your project

   • Open a new terminal via the top menu bar (Terminal) it will be spawned in the container directly.

   • Copy the desired project, e.g.:

     (Note the trailing dot after bfhthesis):

     $ cp -r ${HOME}/texmf/latex_templates/bfhthesis/. .
     

   • Open the main file an press the play button on the top right. It should build the project.

   • You can also use the terminal to build, just run latexmk (a default .latexmkrc is installed in ${HOME} so it should work out of the box)

4. View the generated pdf with live reload

   • Head to the LaTeX extension in the left bar (TEX)

   • COMMANDS->View LaTeX PDF

   • We recommend the browser (View in web browser), since it has shown as the most performant solution, however feel free to use another if it works well

   Note

   The LaTeX extension is configured in a way to detect changes to any tex file automatically to directly rebuild the pdf (it must be saved with e.g. Ctrl+s).

5. The configuration is completed. For more information about the document classes provided by the BFH LaTeX CI, read the section BFH Classes.

Note

For more information about VSCode see the section Tips and Tricks. You can also download the reference sheet with the keyboard shortcuts

Extending the Docker image

It might be that you require additional LaTeX packages for your projects. To install these just add them to the .devcontainer.json in the following way:

.devcontainer.json

"..."
      "valentjn.vscode-ltex"
  ],
 
  "remoteUser": "vscode",
  
  "postCreateCommand": "sudo tlmgr update --self && sudo tlmgr install siunit"
}

This can also be used to automatically configure the git credentials for http:

"postCreateCommand": "git config --global user.email \"example@bfh.ch\""

Warning

We do not recommend to configure git credentials that way, since then this will be the default for any user contributing to this project via VSCode. Instead consider using the host for git operations or mounting the ~/.gitconfig file (and additionally the ssh keys) into the container with the mounts option of the .devcontainer.json (see here)