TODO: we kind of wanted this to be the ID of the toplevel header instead of the first header, but this would require an extra postprocessing pass (to determine if the first header is toplevel or not), which might affect performance, so we are not doing it right now.
When the OurBigBook input comes from a file (and not e.g. stdin), the default ID of the first header in the document is derived from the basename of the OurBigBook input source file rather than from its title.
This is specially relevant when including other files.
For example, in file namedthe ID of the header is
= Awesome ourbigbook file ]]
awesome-ourbigbook-file. See also: automatic ID from title.
For the toplevel index file however, the ID is just taken from the header itself as usual. This is done because you often can't general control the directory name of a project.
For example, a GitHub pages root directory must be named as
<username>.github.io. And users may need to rename directories to avoid naming conflicts.
As a consequence of this, the toplevel index file cannot be included in other files.