Titles

ICG Usage Note

always underline ICG doc titles with “#”

The title is just the “top-level” section in a document, and it may be validly “underlined” with any of the following characters: ! ” # $ % & ‘ ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~ (see Docutils: Sections for complete info).

Tip

It is ok — even a good idea, in the case of a link anchor — to have prefatory, configuration, or other matter above a doc title (comments, special role definitions, link anchors, etc.). The top of this document, for instance, contains an anchor above the title:

.. _icgsphinx_titles:

Titles
######

Build a Link Target for the Whole Document

Though not required, link anchors are commonly seen at the top of documents as the means of making hyperlinks to them possible. Note you don’t see such anchors atop command or FISH docs because these have a customized “built-in” mechanism (the :cmd: and :func: roles) for hyperlinking that makes doc-topping link targets unnecessary.

Consider Adding a Prefix

A prefix is just a comment at the top of the doc that declares a string prefix to be used for link targets within in the doc. See ICG Target Names for details.