OurBigBook
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.htmlis now the split one, andnosplit.htmlis 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
and
Then the following links would be generated:
README.bigb:
= Toplevel
{splitDefault}
\x[h2][toplevel to h2]
\x[notreadme][toplevel to notreadme]
\Include[notreadme]
== h2notreadme.bigb:
= Notreadme
\x[h2][notreadme to h2]
\x[notreadme][notreadme to notreadme h2]
== Notreadme h2index.html: split version ofREADME.bigb, i.e. does not containh2toplevel to h2:h2.html. Links to the split version ofh2, sinceh2is also affected by thesplitDefaultof its parent, and therefore links to it use the split version by defaulttoplevel to notreadme:notreadme.html. Links to non-split version ofnotreadme.htmlsince that header is notsplitDefault, becausesplitDefaultdoes not propagate across includes
nosplit.htmlnon-split version ofREADME.bigb, i.e. containsh2toplevel to h2:#h2, because even thoughh2issplitDefault, that header is already present in the current page, so it would be pointless to reload the split onetoplevel to notreadme:notreadme.html
h2.htmlsplit version ofh2fromREADME.bigbnotreadme.html: non-split version ofnotreadme.bigbnotreadme to h2:h2.html, becauseh2issplitDefaultnotreadme to notreadme h2:#notreadme-h2
notreadme-split.html: split version ofnotreadme.bigbnotreadme to h2:h2.html, becauseh2issplitDefaultnotreadme to notreadme h2:notreadme.html#notreadme-h2, becausenotreadme-h2is notsplitDefault
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/ourbigbook/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.