Split each header into its own separate HTML output file.
This option allows you to keep all headers in a single file, which is much more convenient than working with a billion separate source files, and let them grow naturally as new information is added, but still be able to get a small output page on the rendered website that contains just the content of the given header. Such split pages load faster on the browser, and might get better Google PageRank.
For example given an input file called hello.bigb and containing:
= h1

h1 content.

A link to another section: \x[h1-1].

== h1 1

h1-1 content.

== h1 1 1

h1-1-1 content.

== h1 1 2

h1-1-2 content.
a conversion command:
ourbigbook --split-headers hello.bigb
would produce the following output files:
  • hello.html: contains the entire rendered document as usual.
    Remember that this is called hello.html instead of h1.html because the toplevel header ID is automatically derived from its filename.
    Each header contains a on-hover link to the single-file split version of the header.
  • hello-split.html: contains only the contents directly under = h1, but not under any of the subheaders, e.g.:
    • h1 content. appears in this rendered output
    • h1-1-1 does not appear in this rendered output
    The -split suffix can be customized with the \H splitSuffix argument option. The -split suffix is appended in order to differentiate the output path from hello.html
  • h1-1.html, h1-1-1.html, h1-1-2.html: contain only the contents direcly under their headers, analogously to hello-split.html, but now we don't need to worry about the input filename and collisiont, and just directly use the ID of each header
--split-headers is implied by -p, --publish: the published website will automatically get the split pages. There is no way to turn it off currently. A pull request would be accepted, especially if it offers a ourbigbook.json way to do it. Maybe it would be nice to have a more generalized way of setting any CLI option equivalent from the ourbigbook.json, and an option cli vs cli-publish so that cli-publish is publish only. Just lazy for now/not enough pressing use case met.

Ancestors