## Summary

\setuphead is used to configure headings and titles. Being structuring elements of any document, the possibilities are quite extensive.

## Settings

 \setuphead[...,...][...=...,...] [...,...] section frontpartlabel name bodypartlabel name appendixlabel name backpartlabel name expansion yes no xml catcodes name sectionresetset name sectionseparatorset name sectionconversionset name conversion name sectionstarter command processor->command sectionstopper command processor->command sectionset name sectionsegments number number:number number:* number:all section section:section section:* section:all current referenceprefix + - text style style command color color textstyle style command textcolor color numberstyle style command numbercolor color coupling section ownnumber yes no beforesection command aftersection command insidesection command incrementnumber yes no list empty placehead yes no hidden empty section number yes no page see \page marking page reset header start stop high none normal empty nomarking name text start stop high none normal empty nomarking name footer start stop high none normal empty nomarking name before command after command inbetween command continue yes no aligntitle yes no float interlinespace name interaction list reference internalgrid name grid normal standard yes strict tolerant top bottom both broad fit first last high one low none line strut box min max middle math math:line math:halfline math:-line math:-halfline name align see \setupalign tolerance see \setuptolerance strut yes no hang line broad fit none number margin dimension indentnext yes no auto alternative text paragraph normal margin inmargin top middle bottom reverse margintext name width dimension numberwidth dimension textwidth dimension distance dimension textdistance dimension commandbefore command commandafter command command twoarguments textcommand oneargument deeptextcommand oneargument numbercommand oneargument deepnumbercommand oneargument location name criterium strict positive all hidenumber yes no

OptionExplanation
expansion
 yes expands the xml reference to actual content for title and bookmark \xmlatt {xml:name::4}{title} → First section, see TUC file. To expand userdata also use \normalexpanded{\startsection[title=\xmlatt{#1}{title}]} instead of expansion=yes. \normalexpanded{} and are not in conflict, so you can use both. no no expansion, xml reference is used xml ?
sectionsegments
 which level(s) should be included, e. g. when head is numbered. Note, ":" specifies a range (e. g. "chapter:subsubsection")
style
 The style to use for the heading text. See manual Context: an excursion" section 33, Fonts and font switches, e.g. for large, bold, sans serif section headers use style=\tfa\bf\ss.
aftersection
 Command to run after the section finishes e.g. at a \stopchapter statement.
number
 yes Include number before chapter/section title no Do not include number before chapter/section title
page
 - yes: The section header must be on the top of a new page - left: The section header must be on the top of an even page - right: The section header must be on the top of an odd page
before
 Command to run before the heading is written
after
 Command to run after the heading is written, e.g. after={\blank[3cm]}
continue
 yes If the section immediately follows a chapter it will be on the same page even though page=yes. no If the section immediately follows a chapter it will start on a new page.
aligntitle
 yes use the current local hsize; flush side float first no use the current global hsize float use the current local hsize; do not flush side floats

## Description

To headings is associated the text, i.e. the content of the heading, but can also be associated numbers.

These data can be processed for typesetting :

• add a dot between the text and the number,
• add a generic text before the "pure text"
• appearance can be different for the text if we use it in the headers / footers, or in the Table of Content.
• add vertical spaces before or after the text
• add rules before or after the whole section under the heading
• select if the title should appear on a right or a left page.

## Examples

### First example

\setuppapersize[A5]
\setuplabeltext[chapter=CHAPTER~]

alternative=middle,
style=bold,
numbercommand=\groupedcommand{}{\blank[2cm]},
after={\blank[3cm]},
]

\starttext

\chapter{Title of chapter}

The first paragraph begins 3 cm below the title. In this chapter, we will discuss...

\stoptext


produces

### Big space before a smaller space behind the heading


[subject]
[before={\blank[2*big]},
after={\blank[big]},
style=bold]

\starttext

text text text text text text text text text text text text text text text vtext text text text text text text text text text text text text\par
text text text text text text text text text text text text text text text vtext text text text text text text text text text text text text\par

\stoptext


produces

### Setting label of a new section head

\definehead[mychapter][chapter][bodypartlabel=mychapter]

\setuplabeltext[en][mychapter=My Chapter~]

\starttext
\mychapter{Animals}
\stoptext


produces

### Inline headings similar to LaTeX &squo;s \paragraph{}

\definehead[paragraph][subsubsubsubject]
[
textdistance=0pt,
commandafter={.},
alternative=text,
style=sc,
]

\startparagraph[title=Knuth quote]
\input knuth
\stopparagraph


produces

### Setting label of a part

In MkIV, if you want parts to be labeled as "Part 1" etc., the following isn't sufficient (but works in MkII):

\setuphead[part][placehead=yes]

\starttext
\part{A part}

\stoptext


because it produces

For MkIV, add bodypartlabel=part to the setuphead:

\setuphead[part][placehead=yes, bodypartlabel=part]

\starttext
\part{A part}

\stoptext


(Thanks to Wolfgang Schuster on the mailing list for this information.)

### Example of hidden sections

\setupheadnumber[section]      [8]

\starttext

\section{} % hidden 8th section

\subsection{} % hidden 3rd section

\subsubsection{This is complete numbering of subsubsection} % view 9.4.6 subsubsection

\stoptext


produces

### Modifying the page before a chapter

Here is an example which shows how you can change the background color of an empty page before the chapter title.

% next five lines just to show the effect on this wiki
\setuppapersize[A8][A5,landscape]
\setuppaper[nx=4, ny=2]
\setuplayout[page][location=middle, marking=on]
\setuparranging [XY]
\setupbodyfont[6pt]

% actual example starts here
\setuppagenumbering
[alternative=doublesided]

\startsetups [chapter:before]
\doifoddpageelse
{}
{\pushbackground[page]
\setupbackgrounds[page][background=color,backgroundcolor=gray]
\page[right]
\popbackground}
\stopsetups

[chapter]
[page=yes,
before=\directsetup{chapter:before}]

\starttext

\startchapter[title={Knuth}]
\dorecurse{2}{\samplefile{knuth}}
\stopchapter

\startchapter[title={Ward}]
\dorecurse{1}{\samplefile{ward}}
\stopchapter

\startchapter[title={Zapf}]
\dorecurse{2}{\samplefile{zapf}}
\stopchapter

\stoptext


produces

The command \pushbackground stores the values of the background which is modified. After the execution of \page[right] the old values of background are restored by \popbackground.

### Special facing pages for chapters

On March 7, 2022, Julian asked on the mailing list about some method to place an image on the facing page of each chapter in a (double-sided) book. Chapters might also end on an even (equivalently, left) page, in which case, an empty right (odd) page should be introduced after so that the next chapter still has its image on its facing (left) page. (https://www.mail-archive.com/ntg-context@ntg.nl/msg101455.html)

In the discussion that ensued, Wolfgang posted the following elegant solution using \definepageinjection [slightly re-formatted from (https://www.mail-archive.com/ntg-context@ntg.nl/msg101462.html)] —

% to render examples in the wiki
\definepapersize[sheet][width=24cm,height=24cm]
\definepapersize[page][width=6cm,height=6cm]
\setuppapersize[page][sheet]
\setuppaper[nx=4, ny=4]
\setuparranging [XY]
\setupbodyfont[6pt]

% actual example starts here
\setupexternalfigures
[location=default]

\setuppagenumbering
[alternative=doublesided]

\definepageinjection
[chapter:start]
[empty]
[page=left]

\definepageinjection
[chapter:insert]
[previouspage]
[pagestate=stop,width=\paperwidth]

[chapter]
[beforesection={\pageinjection[chapter:start]},
insidesection={\pageinjection[chapter:insert][name=\structureuservariable{image}]}]

\starttext

\startchapter [title={Cow}] [image=cow]
\dorecurse{2}{\samplefile{klein}}
\stopchapter

\startchapter [title={Mill}] [image=hacker]
\dorecurse{4}{\samplefile{lorem}}
\stopchapter

\startchapter [title={Mill}] [image=mill]
\dorecurse{2}{\samplefile{klein}}
\stopchapter
\stoptext


which produces