This is the part of the documentation where ConTeXt is indeed
seriously lacking. There seems to be no good and complete
introductory book for ConTeXt, while there exist literally hundreds of
more or less good books for LaTeX. But do not despair,
there is still a way for a beginner to start getting into ConTeXt and
here is how.
- ConTeXt Mark IV an excursion This is the successor
of ConTeXt an excursion which is often put forward as
the beginner's guide. However, ConTeXt an excursion
was written in 1999 for ConTeXt MkII and therefore contains a lot
of information which is outdated in MkIV. Some people have
complained that the layout is horrible but I think this document
gives a very nice overview over the most frequently used commands
on about 100 pages. Unfortunately I still couldn't typeset
ConTeXt documents after reading this. I now knew what the
building blocks are but I still had no idea how to put them
together. That is where the next resource enters...
- Creating a clean presentation style in 40 commits
An amazing tutorial by Aditya Mahajan where a set of presentation
slides is built step by step. You can either browse the commits
on GitHub, use the
git-walk tool (instructions provided
on Aditya's blog), or view all the details on a single page.
This tutorial equipped me with the
basic understanding of how to customize the most relevant elements
of the document.
- ConTeXt command reference Now that you know how to
customize your documents, you of course want to try out all the
different settings. But wait, what are actually all the
settings? What are the possible keys of, e.g.
is where the ConTeXt command reference comes in. This extremely
minimalistic document is the most helpful I have encountered so
far. On over 300 pages every setup command with all accepted keys
This concludes the section on introductory material. From here on we
dive into more complicated topics. Nevertheless after reading the
references (1) and (2) and having (3) at hand you should be able to
compose your first documents.
I don't recommend that you try to read these references as a whole.
There is no way you can memorize all that stuff. Just skim through it
to get an idea of what is there, so you can come back and read in
detail when you actually need it.
You have probably started writing your own macros and are getting in
contact with the ConTeXt core and are wondering what all those weird
\@@ are. Then you might enjoy the
System Macros page in the ConTeXt Garden Wiki.
- Fonts out of ConTeXt a.k.a “the new font manual”
supersedes the old Fonts chapter. Once in a while you
want to tweak things like ligatures, kerning, protrusion, or even
want to do complicated things like defining a virtual font to
display your custom characters. This is the go-to resource for
all those complicated font-related questions.
- Typescript files If you only want to implement a
typescript for a font which does not have one provided you are
much better off just browsing the ConTeXt source for the
type-imp-*.mkiv files and see how it's done there.
- ConTeXt rehab for amsmath addicts This is a short
article which appeared in 2006 in the MAPS journal of the Dutch
TeX user group. It details how to achieve similar alignments to
the ones known from the LaTeX
amsmath package. (This article
appeared also in My Way)
- math This manual discusses some advanced math stuff,
like automatic replacements (the input
/= is automatically
≠), interplay with grid typesetting, custom
numbering, and some tricks for deficient math fonts.
- Bibliographies the ConTeXt way Probably
you read about
\setupbibtex in ConTeXt Mark IV an
excursion. This mechanism has been superseded by the
btx mechanism which acts as a replacement for BibTeX,
entirely implemented in Lua. Thanks to
btx ConTeXt does not
depend on external programs for processing bibliographies.
However, it only provides two different styles:
apa as an
author-year style and
aps as a numeric style. A verbose style
ieee is in development.
Interaction with Lua
- ConTeXt Lua Documents ConTeXt MkIV is based on
LuaTeX and LuaTeX development is driven solely by ConTeXt. It is
not surprising to find that there is amazing interaction between
ConTeXt and Lua and in principle you can typeset whole documents
in Lua. Some things, like the PDF backend, have spare or don't
have macro-level interfaces at all. Such low-level mechanisms are
usually accessible in Lua.
Metafun Metafun is a set of MetaPost macros,
specifically tailored for the interaction with ConTeXt. You can
do a lot of fun things, like overlays, drawing font outlines, or
just basic shapes. A LaTeX user would use TikZ for that (which
is also available in ConTeXt) but Metafun runs orders of
magnitudes faster and integrates quite naturally with everything
related to frames, such as backgrounds, tables, and plain frames
Flowcharts Macro-level interfaces for drawing
flow charts in Metafun. Flowcharts are not part of the core
functionality and have to be imported using
Nodes Macro-level and MetaPost interfaces for drawing
- It's in the details I consider this to be one of the
most important documents for the advanced ConTeXt user. It is a
visual guide to all the cool features which made you switch from
LaTeX to ConTeXt, namely grid typesetting and sidefloats. As
already noted, this is a visual guide and not really a manual
which explains a lot of things. Rather it lists different options
and shows the visual effects of setting those options.
- Pages Behind this rather misleading title hides
a manual on how to typeset magazine style columns with floats
which can span several columns.
The progress reports A lot of features which get added to
ConTeXt are rather minor or affect the core directly, so they do
not have dedicated manuals. Nevertheless, Hans tirelessly
documents these features in his progress reports on LuaTeX and
ConTeXt development. In chronological order these are:
The history of LuaTeX has mostly historical relevance
because a lot of features described in there are documented
elsewhere in much more detail, like OpenType fonts,
Metafun, and XML.
The other documents give a very in-depth view of all the internals
of ConTeXt MkIV and it is definitely worth skimming through them
to see what is available. Whenever I open these manuals and read
a few paragraphs I find new hidden features.
- Dealing with XML in ConTeXt MkIV ConTeXt can export
documents to XML. This is possible thanks to the monolithic core
and unified interfaces. It is also possible to generate typeset
output from XML input. This manual details all the XML
interaction with the macro and the Lua level.
- LuaTeX Because the relationship between ConTeXt MkIV
and LuaTeX is so close it is absolutely necessary for the expert
user to know the details of the underlying engine. The link
points to the LuaTeX manual hosted on Pragma ADE which always
covers the latest development version used as a basis for ConTeXt
All the manuals listed above are also shipped with the installation of
ConTeXt standalone and TeX Live. The PDFs can be found in
doc/context/documents/general/manuals/, the corresponding
links point to the ConTeXt GitHub mirror).
In TeX Live, manuals can also be opened using the
texdoc tool by
providing the name of the PDF as an argument, e.g.
will open the MetaFun manual.
There are two other manuals which I see mentioned in some places and I
want to give my comments on these.
Typographic Programming This is supposed to grow into a
manual about general aspects of document design and how to
translate design into style by the means of automated typesetting.
At the moment it is unfinished and is mostly about
microtypographic features and page layout but doesn't go beyond
the much more complete Fonts out of ConTeXt and
It's in the details. It also hasn't been updated in
ConTeXt reference manual This was supposed to be a
comprehensive introduction to ConTeXt and could have evolved into
a complete introductory user manual but got stuck somewhere
halfway between MkII and MkIV with a few missing chapters. I
don't recommend reading it before you have a solid understanding
of the difference between MkII and MkIV, because otherwise it is
just too confusing.
There is also the command reference on the ConTeXt Garden
Wiki. This is a total hit and miss because some commands are
documented really well, others not at all. The good thing is that it
is publicly editable, so if you encounter bad documentation you should
log in and fix it.