Figures and Floats

Including figures

According to ConTeXt gurus, good practice requires that we take three minimal steps to place a figure.

  1. Define a directory where we can find the figure with the setupexternalfigures command.

  2. Set up the picture by telling ConTeXt by giving it a name, a location, and by setting up other options. Use the useexternalfigure for this.

  3. Placing the figure with a externalfigure command.

You can use a shortcut to combine steps one and two, but we’ll stick with the longer method for consistency.

Setting up figures default

The setupexternalfigures command can tell ConTeXt where to search for your graphics. ConTeXt will look in your present directory to find the graphics. If you graphics are in another directory, use the directory option. The path takes unix-style syntax, and can be an absolute or relative.

% look in the same parent directory as the tex file for a 
% directory called pngImages


  • You can also set the maxwidth and maxheight with this command. setupexternalfigures[maxheight=5in]

  • You can also set as your first option the frame or empty. frame puts a frame around each figure. empty does not place the text, but does reserve the necessary space, so is useful for test runs.

Setting up options for individual figure

The useexternalfigure command allows you to to create many options for the figure, such as how much you scale it.

For our sake, put a reference in the first option of this command. Use any unique name, such as “figure 1” or “dolpin 1”.

In the second option, put the name of the actual graphic as it is on your system, minus the extension and minus the directories. If the path to the graphic is “/home/paul/graphics/thoreau.jpg,” you would simply write “thoreau”.

\useexternalfigure[dolphin ref][dophin]

Placing the figure

Place the figure with the externalfigure command.

% place the figure
\externalfigure[thoreau ref]


  • This is the simplest way to place a figure. You can also place it as a float (see below), which gives you more control over placement.

  • The placefigure command also takes a second optional option. This option can be any of the values we mentioned above, such as height or scale. externalfigure[thoreau ref][scale=500]. Obviously, it makes no sense to define values such as scale in both the useexternalfigure and placefigure command. However, sometimes it is useful to do scaling in the useexternalfigure command, especially when you are using floats in combination with buffers. (See below.)


Floats are elements like tables or figures that are placed (and numbered) automatically by ConTeXt. For XML, we don’t need the automatic numbering, but we do need the care ConTeXt takes in making sure a float fits on a page, and that the caption fits with it.

The placetable is an example of a float. However, there are other ways to place a table.

customizing captions

In order to customize your captions, use the setupcaptions command. The first option of this command defines the type of caption: table, figure, etc. The second option defines the actual setups, including the placement, alignment, and font-style.


A float for a figure is set up with the placefigure command.

Moving floats

One should be able to easily move floats around. Imagine that you are using a gui application, like MS Word, or something professional like Quark Express. You have imported a picture into this appliation. You place your mouse on the picture and move the picture up or down. You go to a dialogue box and determine how much space should go before the picture and the float. Commercial applications have been able to perform these basic operations for over 20 years.

Unfortunately, I don’t see a similar way to perform the same function in ConTeXt. The ConTeXt mailing list pointed me to a PDF document with so much complicated code that after 1 hour of not finding anything close to a solution, left me with a feeling of despair about the usefullness of ConTeXt. Hopefully I will stumble upon a solution that will prove my frustration was for nothing.

copyright 2005 Paul Henry Tremblay

License: GPL

home | contents | previous | next Logo

last updated: 2005-04-19