Heading formats (titlesec)

The typeface, numbering, and surrounding space of \section or \chapter are normally decided by the document class. The **titlesec** package (by Javier Bezos) lets you redesign all of that from your own preamble. Its two pillars are \titleformat, which defines a heading’s look, and \titlespacing, which defines the space around it. The document structure itself is covered in “Structure, headings & ToC” — here we dig only into how the headings *look*.

The quick setup first

Before the fine-grained definitions, titlesec offers an “easy setup” that changes the look through package options alone. Loading it as \usepackage[sf,bf]{titlesec}, for instance, makes every heading sans-serif and bold. The options come in three groups, each with a default, so you only specify the ones you want to change.

Independently of those, the compact option tightens the space above and below titles. To change how the *number* prints, use **\titlelabel**: \thetitle stands for the heading’s number, and the standard-class default is \titlelabel{\thetitle\quad}. If you merely want a period after the number, write it like this.

\usepackage[sf,bf]{titlesec}     % 見出しをサンセリフ＋ボールドに
\titlelabel{\thetitle.\quad}     % 「1.」のように番号のあとにピリオド

And when you want to change only the font, leaving the number and spacing alone, the starred **\titleformat*** is the shortest route. Pass the sectioning command and the desired font; the title’s *shape* stays as the class set it, and only its appearance changes.

\titleformat*{\section}{\large\bfseries\sffamily}     % \section の書体だけ差し替え

Defining the look with \titleformat

The full redesign is done by (un-starred) **\titleformat**. It takes a daunting number of arguments, but each is straightforward once you take them one at a time. The overall shape is this.

\titleformat{⟨command⟩}[⟨shape⟩]{⟨format⟩}{⟨label⟩}{⟨sep⟩}{⟨before-code⟩}[⟨after-code⟩]

• ⟨command⟩** — the very sectioning command you are redesigning: one of \part, \chapter, \section, \subsection, \subsubsection, \paragraph, \subparagraph.
• [⟨shape⟩]** (optional) — the title’s “shape”: hang, block, display, runin, leftmargin, frame, and others below. Defaults to hang.
• {⟨format⟩} — formatting applied to both** the label and the body. Set typeface, size, and alignment together here, e.g. \normalfont\Large\bfseries.
• {⟨label⟩}** — how the number (label) prints; put \thesection and the like. You may leave it empty for an unnumbered level, but then the number is suppressed in the table of contents too.
• {⟨sep⟩} — the gap between label and body. It must be a length and may not be empty** (horizontal in hang/block, vertical in display, the text-to-frame distance in frame).
• {⟨before-code⟩} — code run just before** the title body. Its last command may take one argument, which becomes the title text.
• [⟨after-code⟩] (optional) — code run just after** the title body (vertical mode in hang/block/display, horizontal mode in runin/leftmargin).

The ⟨shape⟩ sets the basic layout of the heading. Here are the ones you will reach for.

Defining the spacing with \titlespacing

The companion to the look is **\titlespacing, which sets the space around a heading. You normally use the starred \titlespacing***.

\titlespacing*{⟨command⟩}{⟨left⟩}{⟨before-sep⟩}{⟨after-sep⟩}[⟨right⟩]

• ⟨left⟩** — how much to increase the left margin (in the leftmargin shapes it sets the title width; in runin, the indentation just before the title).
• ⟨before-sep⟩ — the vertical space above** the title.
• ⟨after-sep⟩** — the separation between title and body (vertical in hang/block/display, horizontal in runin/leftmargin).
• [⟨right⟩]** (optional) — increases the right margin in hang/block/display.

The meaning of the star is the crux here: **the starred \titlespacing* suppresses the indentation of the paragraph that follows the title.** LaTeX has a convention of not indenting the paragraph right after a heading, and the star selects that behaviour (in the drop, wrap, and runin shapes this possibility does not apply, so the star has no effect). Every argument must be a length (a dimension); a value containing a command, such as \stretch, raises an error. If typing the full skip values is tiresome, you can abbreviate with * and a number, as in *4, with \beforetitleunit and \aftertitleunit serving as the units.

A worked example

\titleformat and \titlespacing are usually written as a pair. The preamble below redesigns \section so that a thin rule sits to the left, with the number and title set beside it in a larger sans-serif bold.

\documentclass{article}
\usepackage{titlesec}

\titleformat{\section}            % 対象は \section
  [hang]                          % 形：番号をぶら下げる
  {\sffamily\Large\bfseries}      % 番号・本文に効く書式
  {\thesection}                   % ラベル（番号）
  {1em}                           % ラベルと本文の間隔
  {}                              % 本文直前のコード（ここでは無し）

\titlespacing*{\section}
  {0pt}                           % 左余白の追加なし
  {3.5ex plus 1ex minus .2ex}     % 見出しの上の空き
  {2.3ex plus .2ex}               % 見出しと本文の間の空き

\begin{document}
\section{はじめに}
本文がここから続きます。
\end{document}

In this \titleformat, [hang] selects the hanging-label shape, and {\sffamily\Large\bfseries} applies to both the number and the title. {\thesection} prints the number (“1,” “2,” …), and {1em} is the gap between that number and the title. The final {} is the code before the body — here it does nothing. The following \titlespacing* adds no left margin (0pt), puts about 3.5ex above the heading, and about 2.3ex between heading and body. The plus/minus parts are the allowed stretch and shrink — the “give” that lets LaTeX balance the page. Because it is starred, the paragraph right after \section is not indented. To add the rule, the idiom is to place titlesec’s \titlerule in {⟨before-code⟩} and switch to the [display] shape.

By default the title text follows {⟨before-code⟩} implicitly, but the **explicit option changes this: you must then place the title text explicitly** with #1 (e.g. \titleformat{\section}{..}{\thesection}{..}{#1.}). It is useful when you want decoration on both sides of the title.

Matching the ToC with titletoc, and caveats

Once you have restyled the headings, you usually want the table of contents to match. For that, titlesec ships with a companion package, **titletoc** (which can also be used on its own). Its core is \titlecontents, which fully defines a contents entry, and \dottedcontents, a one-shot preset with dotted leaders. Note that the leading ⟨section⟩ argument is the name without a backslash (section, chapter, figure, …).

\usepackage{titletoc}
% 節の目次項目：点線リーダー付き（左寄せ 1.5em、ラベル幅 2.3em、リーダー幅 1pc）
\dottedcontents{section}[1.5em]{}{2.3em}{1pc}

Finally, two pitfalls people commonly hit. First, **\titlespacing does not work with \chapter or \part unless you also change their format** via \titleformat (or the easy setup). \part is implemented in a non-standard way, so the simple settings leave it untouched; change it through \titleformat instead. Second, **titlesec does not get along with the KOMA-Script classes** (scrartcl and friends). KOMA-Script warns that using the two together is not recommended, and several features break — the headings option and the extended optional argument of the section commands among them. If you use KOMA-Script, restyle headings with KOMA’s own mechanism (\setkomafont, \RedeclareSectionCommand) rather than titlesec.