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 named
the ID of the header is
my-file.bigb
which contains:
= Awesome ourbigbook file
my-file
rather than awesome-ourbigbook-file
. See also: automatic ID from title.If the file is an index file other than the toplevel index file, then the basename of the parent directory is used instead, e.g. the toplevel ID of a file:
would be:
rather than:
my-subdir/README.bigb
#my-subdir
#README.bigb
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.