The ID of the first header is derived from the filename

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.

The only exception to this is the home article, where the ID is empty.

For example, in file named my-file.bigb which contains:the ID of the header is my-file rather than awesome-ourbigbook-file. See also: automatic ID from title.

An explicit {id=...} on this first header is an error, even if it matches the filename: rename the file to change its ID. This also applies to index files in subdirectories. The argument remains available on other headers, on input without a filename, and in the Web editor where it determines the article path. {disambiguate=...} is still allowed on filename-derived headers because it affects the displayed title and the {wiki} target.

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:

For the toplevel index file, the ID is empty, independent of the title and project directory name. A nonempty {id=...} is already forbidden there.

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.

The toplevel index file cannot be included in other files.

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.