OurBigBook logoOurBigBook Docs OurBigBook logoOurBigBook.comSite Source code

-S, --split-headers (Split headers)

Split each header into its own separate HTML output file.
This option allows you to keep all headers in a single source 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:
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 the --publish option: 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 (3)

  1. OurBigBook CLI options
  2. OurBigBook CLI
  3. Home

Incoming links (20)

Synonyms (1)