OurBigBook Web implements what we call "dynamic article tree".
What this means is that, unlike the static website generated by OurBigBook CLI where you know exactly which headers will show as children of a given header, we just dynamically fetch a certain number of descendant pages at a time.
As an example of dynamic artic tree, note how the article "Special relativity" can be seen in all of the following pages:
The only efficient way to do this is to pick which articles will be rendered as soon as the user makes the request, rather than having fully pre-rendered pages, thus the name "dynamic".
Video 10. OurBigBook Web dynamic article tree. Source.
The design goals of the dynamic article tree are to produce articles such that:
  • each article can appear as the toplevel article of a page to get better SEO opportunities
  • and that page that contains the article can also contain as many descedants as we want to load, not jus the article itself, so as to not force readers to click a bunch of links to read more
For example, with a static website, a user could have a page structure such as:
natural-science.bigb
= Natural science

== Physics

\Include[special relativity]
special-relativity.bigb
= Special relativity

== Lorentz transformation
In the static output, we would have two output files with multiple pages:
  • natural-science.html
  • special-relativity.html
plus one split output file for each header if -S, --split-headers were enabled:
  • natural-science-split.html
  • physics.html
  • special-relativity-split.html
  • lorentz-transformation.html
In this setup the header "Physics" for example is present in one of two possible pages:
  • natural-science.html: as a subheader, but Special Relativity is not shown even though it is a child
  • physics.html: as the top header, and Special Relativity is still not shown as we are in split mode
In the case of the dynamic article tree however, we achieve our design goals:
  • "Physics" is the toplevel header, and therefore can get much better SEO
  • "Special Relativity", "Lorentz transformation" and any other descendants will still show up below it, so it is much more readable than a page
We then just cut off at a certain number of articles to not overload the server and browsers on very large pages. Those pages can still be accessed through the ToC, which is currently unlimited. We also want to implement: load more articles to allow users to click to load more articles.
And all of that is achieved:
  • without requiring authors to manually determine which headers are toplevel or not to customize page splits with reasonable load sizes.
  • without keeping multiple copies of the render output of each page and corresponding pre-rendered ToCs. On the static website, we already had two rendering for each page: one split and one non-split, and the ToCs were huge and copied everywhere. Perhaps the ToC side could be resolve with some runtime fetching of static JSON, but then that is bad for SEO.
The downside of the feature is slightly slower page loads and a bit more server workload. We have kept it quite efficient server-side by implementing the page fetching with a nested sets implementation: stackoverflow.com/questions/4048151/what-are-the-options-for-storing-hierarchical-data-in-a-relational-database
We believe that dynamic article treee offers a very good tradeoff between server load, load speeds, SEO, readability and author friendliness.

Ancestors