When using -S, --split-headers, cross references always point to non-split pages as mentioned at cross reference targets in split headers.
If the splitDefault boolean argument is given however:
  • the split header becomes the default, e.g. index.html is now the split one, and nosplit.html is the non-split one
  • the header it is given for, and all of its descendant headers will use the split header as the default internal cross target, unless the header is already rendered in the current page. This does not propagate across includes however.
For example, consider README.bigb:
= Toplevel

\x[h2][toplevel to h2]

\x[notreadme][toplevel to notreadme]


== h2
and notreadme.bigb:
= Notreadme

\x[h2][notreadme to h2]

\x[notreadme][notreadme to notreadme h2]

== Notreadme h2
Then the following links would be generated:
  • index.html: split version of README.bigb, i.e. does not contain h2
    • toplevel to h2: h2.html. Links to the split version of h2, since h2 is also affected by the splitDefault of its parent, and therefore links to it use the split version by default
    • toplevel to notreadme: notreadme.html. Links to non-split version of notreadme.html since that header is not splitDefault, because splitDefault does not propagate across includes
  • nosplit.html non-split version of README.bigb, i.e. contains h2
    • toplevel to h2: #h2, because even though h2 is splitDefault, that header is already present in the current page, so it would be pointless to reload the split one
    • toplevel to notreadme: notreadme.html
  • h2.html split version of h2 from README.bigb
  • notreadme.html: non-split version of notreadme.bigb
    • notreadme to h2: h2.html, because h2 is splitDefault
    • notreadme to notreadme h2: #notreadme-h2
  • notreadme-split.html: split version of notreadme.bigb
    • notreadme to h2: h2.html, because h2 is splitDefault
    • notreadme to notreadme h2: notreadme.html#notreadme-h2, because notreadme-h2 is not splitDefault
The major application of this if you like work with a huge README.bigb containing thousands of random small topics.
Splitting those into separate source files would be quite laborious, as it would require duplicating IDs on the filename, and setting up includes.
However, after this README reaches a certain size, page loads start becoming annoyingly slow, even despite already loading large assets like images video videos only on hover or click: the annoying slowness comes from the loading of the HTML itself before the browser can jump to the ID.
And even worse: this README corresponds to the main index page of the website, which will make what a large number of users will see be that slowness.
Therefore, once this README reaches a certain size, you can add the splitDefault attribute to it, to make things smoother for readers.
And if you have a smaller, more self-contained, and highly valuable tutorial such as cirosantilli.com/x86-paging, you can just split that into a separate .bigb source file.
This way, any links into the smaller tutorial will show the entire page as generally desired.
And any links from the tutorial, back to the main massive README will link back to split versions, leading to fast loads.
This feature was implemented at: github.com/cirosantilli/ourbigbook/issues/131
Note that this huge README style is not recommended however. Ciro Santilli used to do it, but moved away from it. The currently recommended approach is to manually create not too large subtrees in each page. This way, readers can easily view several nearby sections without having to load a new page every time.