Input and compilation/Text editors/TeXShop

Unofficial ConTeXt Wiki mirror

Last modified: 2026-01-15

TeXShop is a good editor for all variants of TeX and ConTeXt. It offers:

Here, only a summary of the main configuration relevant to ConTeXt is provided. This should get you up and running, but for more detailed documentation, refer to TeXShop > Help > TeXShop Manual. Also, check the stuff inside ~/Library/TeXShop/, in particular, the folders Engines/Inactive/ConTeXt, and ExternalEditorScripts if you plan to use TeXShop as a previewer for an external editor.

It is possible to select the engine used to typeset a document from the document's toolbar. If no ConTeXt option is present, proceed as follows: 

chmod +x ~/Library/TeXShop/Engines/ConTeXt*.engine

You may close the terminal.

Remark those engines use context and not mtxrun for compilation. See below how to add an engine using the latter instead.

Select a ConTeXt engine from the drop-down menu and click Typeset. If there are no errors the output will appear in a viewer window.

It is possible to specify which engine to use with each document by adding some “magic lines” right at the beginning of your source document. For example: 

% !TEX TS-program = ConTeXt-CG
% !TEX useAlternatePath

When those lines are present, they override the selection in the toolbar. Verify in the Console window that the correct ConTeXt distribution is used for typesetting.

Syncing between Source and PDF

As of July 2021, ConTeXt provides support, through its Swiss army knife mtxrun script, for getting the filename and line corresponding to a certain spot in a PDF document, and for getting the PDF coordinates (page number + bounding box) corresponding to a given line in a source file. Type this in a terminal window to get some information about this nifty feature: 

mtxrun --script synctex --help

Editors can exploit this feature to provide smooth syncing between source code and PDF.

TeXShop v4.66 and later has adopted ConTeXt's syncing method. When this method is enabled (see the “magic line” below), Cmd-clicking somewhere in the preview window jumps to the source window and highlights the corresponding line. Vice versa, Cmd-clicking somewhere in a source window jumps to, and highlights, the corresponding spot in the preview.

To enable syncing:

  1. Make sure that you are using the latest ConTeXt release
  2. Make sure that you are using TeXShop v4.66 or later
  3. Add the following “magic lines” at the start of your source document: 
    % !TEX useAlternatePath
% !TEX useConTeXtSyncParser
  4. Make sure that your document generates a .synctex file. Your source should contain this line: 
    \setupsynctex[state=start,method=min]

    or this: 

    \setupsynctex[state=start]
  5. Make sure the TeXShop preferences setting “alternate path” is set to the path to your LMTX installation. A typical example for an Intel-based Mac is: 
    TeXShop -> Preferences -> Engines -> Alternate path == /Users/<username>/Applications/context-osx-64/tex/texmf-osx-64/bin

    If you do not do this or get this wrong then the editor will fail to sync from source to PDF or back without any error message.

You may find that you need to quit and restart TeXShop to get it to take account of changes you make to the above.

Then, typeset your document and try Cmd-clicking either in the source or in the preview. This is a minimal example that allows you to test syncing within TeXShop: 

% !TEX TS-program = ConTeXt-CG
% !TEX useAlternatePath
% !TEX useConTeXtSyncParser

\setupsynctex[state=start,method=min]

\starttext
Sed ut perspiciatis unde omnis iste natus error sit voluptatem
accusantium doloremque laudantium, totam rem aperiam, eaque
ipsa quae ab illo inventore veritatis et quasi architecto
beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem
quia voluptas sit aspernatur aut odit aut fugit, sed quia
consequuntur magni dolores eos qui ratione voluptatem sequi
nesciunt. Neque porro quisquam est, qui dolorem ipsum quia
dolor sit amet, consectetur, adipisci velit, sed quia non
numquam eius modi tempora incidunt ut labore et dolore magnam
aliquam quaerat voluptatem. Ut enim ad minima veniam, quis
nostrum exercitationem ullam corporis suscipit laboriosam, nisi
ut aliquid ex ea commodi consequatur? Quis autem vel eum iure
reprehenderit qui in ea voluptate velit esse quam nihil
molestiae consequatur, vel illum qui dolorem eum fugiat quo
voluptas nulla pariatur?
\stoptext

Syncing works even with complex documents made of several source files. Backward syncing (from PDF to source) works without any additional settings. To make forward syncing work (i.e., jumping from an included source to the PDF), you need to tell TeXShop which is the “root” document of each included file. That is done by adding yet another “magic line” to all included sources: 

% !TEX root = <MAIN>.tex

where <MAIN>.tex is the name of your root source. If your included files are in a different folder, you need to specify the correct (relative) path to the root document. Refer to TeXShop's documentation to learn more about this and the other “magic lines”.

TeXShop still supports an old syncing method, which is based on Jérôme Laurens's SyncTeX, but using that for ConTeXt is not recommended any longer, so how to use that will not be explained in this document. Just note that the Sync Method preference in Preferences > Typeset is not relevant for the new syncing method described above; it is strongly recommended that it is set to SyncTeX (TeX ≥ 2010) anyway.

Syncing with an External Editor

TeXShop can be used as a previewer for an external editor. If you want to edit your source files in a different editor, go to TeXShop > Preferences > Source, and check Configure for External Editor. Then, close and reopen TeXShop.

Detailed instructions about configuring TeXShop to synchronise with an external editor are provided in TeXShop > Help > TeXShop Manual. Such instructions will not be repeated here, also because they depend on which editor you are using. We only mention that you will need to execute this command in a terminal: 

   defaults write TeXShop OtherEditorSync YES

and you will need to create a small shell script called /usr/local/bin/othereditor containing a command that TeXShop can use to call your editor. See TeXShop's manual for details.

Troubleshooting

No synchronization happens either way

Synchronization from source to PDF does not work 

SyncTeX Version:1
Input:1:/some/absolute/path/to/main.tex

then syncing from the editor to the viewer will work only if the editor calls mtxrun --script synctex with absolute paths. If the .synctex file is a relative path: 

SyncTeX Version:1
Input:main.tex

then syncing will work only if the editor calls mtxrun --script synctex with relative paths. Make sure your editor is configured accordingly.

Synchronization from PDF to source does not work

Synchronization works, but the target location is wrong

First of all, keep in mind that synchronization should jump to an approximately correct location. That said, if it seems that a blatantly wrong location is hit, you may debug the issue by running mtxrun directly.

For instance, if test.tex is the name of the minimal example above, then a terminal session may go like this ($ is the shell prompt: it must not be typed): 

$ cd <path to test.tex source directory>
$ export PATH=~/context-osx-64/tex/texmf-osx-64/bin:$PATH  # If necessary (adapt the path to match your system)
$ mtxrun --script context --autogenerate test.tex

Now, a file called test.synctex should exist. Test ConTeXt's synctex script for forward syncing: 

$ mtxrun --script synctex --find --file=test.tex --line=12 --direct test.synctex

page=1 llx=354 lly=178 urx=423 ury=193

The output shows the page in PDF to jump to and the bounding box of the region to highlight. Then, test backward syncing: 

$ mtxrun --script synctex --report --page=1 --x=350 --y=180 --console test.synctex
"test.tex" 11 0

The output shows the source path, the line number (11), and a tolerance (0), which will be positive if the input coordinate is slightly outside any bounding box recorded in the .synctex file.

If mtxrun output looks accurate enough, then probably TeXShop is at fault; otherwise, report the issue to ConTeXt's mailing list.

Making UTF-8 Default File Encoding

ConTeXt uses UTF-8 as its default encoding, so it is best to make this the default encoding for your files. You can also choose whichever encoding you wish. You can also set the file encoding when a document is saved. TeXShop will automatically recognize the file encoding of existing files and use that when saving the file.

To make TeXshop use utf-8 as its standard encoding for files, proceed as follows:

Creating an Engine for TeXShop

Actually, engine is somewhat misleading. In TeXShop an engine is a script that contains commands that are use to typeset your documents. TeXShop comes with many engines set up to run TeX, LaTeX, Xe(La)TeX and ConTeXt MKII and MKIV that have been installed via MacTeX.

If you want to use ConTeXt Suite you will have to create an TeXShop-engine.

If you have not run TeXShop start it so that the support files for TeXShop are installed for you.

Since in the newer versions of MacOS the users Library-folder is hidden and not accessible from within TeXShop we will use the terminal for simplicity reasons. If you wish you can access the your Library-folder from the Finder and navigate to the Engines-folder inside of the TeXShop-folder inside your Library-folder and choose a ConTeXt-engine. 

open -a TeXShop $HOME/Library/TeXShop/Engines/ConTeXt\ \(LuaTeX\).engine
This will open the file in TeXShop and switch to TeXShop 
 option click on the File menu 
 choose "Save As …"
 change (LuaTeX) in the Name field to Suite
 hit return
 

set path= (/Users/username/context/tex/texmf-osx-64/bin  $path /usr/local/bin)
If you installed in a different location then change /Users/username/context/ to the location where you installed ConTeXt standalone. Do not forget to change username in the line above to your actual username!!

You can now use your new engine by choosing it from the Pop-up Menu of your document window.

If you want other options or use MKII then create a new engine and change the line containing mtxrun accordingly.

In the manual for TeXShop you can find instructions for making your engine the the default engine or how to have TeXShop use your engine no matter which engine is set on a file by file basis.

Setting-Up TeXShop for ConTeXt Suite

TeXShop installs support files for the user in ~/Library/TeXShop. Let's create an engine for mtxrun:

In the dialog window change the name of the file to ConTeXt Suite.engine or whatever!
In the lower part of the dialog change the file format to Plain Text 
 #!/bin/tcsh
 echo "$path"
 setenv PATH "$3"\:$PATH
 echo "$path"
 "$3"/mtxrun --autogenerate --script context --autopdf --synctex=1 "$1"
 

 chmod +x LMTX.engine
In one window navigate to where you saved the engine
In the other window navigate to the folder containing the engines for TeXShop. (Press shift -cmd-G and in the dialog enter: ~/Library/TeXShop/Engines

Setting-Up TeXShop for ConTeXt Suite System-Wide Installation

Making a decent tutorial for setting-up TeXShop for a ConTeXt Suite system-wide installation is kind of difficult, because TeXShop installs support files for each user which become unique to each user after it has been started for the first time by the user. The problem is how get the needed engine/s for the ConTeXt Suite into the user support files.

You can put the engine in into the application bundle of TeXShop, so that it will be installed for every user the first time they run TeXShop or a new version of TeXShop is run. Of course you have to the engine into the application bundle of each update to TeXShop!

In the dialog window change the name of the file to ConTeXt Suite.engine or whatever!
In the lower part of the dialog change the file format to Plain Text 
 #!/bin/tcsh
 
 set path= (/Users/quayjay/context/tex/texmf-osx-64/bin  $path /usr/local/bin)
 mtxrun --script context --autogenerate --synctex=1 "$1"
In one window navigate to where you saved the engine
In the other window navigate to the Applications-folder and to where TeXShop was installed.
If you installed via MacTeX you will find it in Applications->TeX->TexShop

'IMPORTANT:' The newly created engine will not be installed if a user has already run TeXShop! If a user has already run TeXShop then the newly created engine must copied to their Engine-folder inside of their TeXShop-folder inside their Library-folder!!

Do not forget that you have to also copy your own copy of the newly created engine to your own Engine-folder!!

Viewing the PDF in Preview using thumbnail view

TeXShop has a "View pdf with Preview" macro in the Macros->AppleScript menu. This opens the current PDF in normal page view. However, Preview is also able to view a PDF as thumbnails which can be very useful for seeing the effect of changes on the overall document layout.

The following change enables Preview to open the PDF in thumbnail view by default. 

   --AppleScript direct
    
   tell application "Preview"
     activate
     open POSIX file #PDFPATH#
     set bounds of front window to {60, 60, 1400, 1200} -- optional: allows 4 thumbnails across
   end tell
   tell application "System Events" to tell application process "Preview"
       click (menu item "Contact Sheet" of menu "View" of front menu bar)
   end tell

Note: the first time you run the macro you will be prompted to give permission for TeXShop to control Preview via Accessibility. This is normal.

I've mapped the macro to the cmd-R key combination as this makes it simple to 'review' the whole document.

If you decide to undo the changes then go back to the macro editor and remove the last tell...end tell block.