OurBigBookThis section describes the philosophy of internal cross references.
In many static website generators, you just link to URL specific paths of internal headers.
In OurBigBook, internal cross references point to IDs, not paths.
For example, suppose "Superconductivity" is a descendant of "Condensed Matter Physics", and that the source for both is located at
condensed-matter-physics.bigb, so that both appear on the same .html page condensed-matter-physics.html.When linking to Superconductivity from an external page such as
statistical-physics.bigb you write just <superconductivity> and NOT <condensed-matter-physics#superconductivity>. OurBigBook then automatically trakcs where superconductivity is located and produces href="condensed-matter-physics#superconductivity" for you.This is important because on a static website, the location of headers might change. E.g. if you start writing a lot about superconductivity you would eventually want to split it to its own page,
superconductivity.html otherwise page loads for condensed-matter-physics.html would become too slow as that file would become too large.But if your links read
<condensed-matter-physics#superconductivity>, and all links would break when you move things around.So instead, you simply link to the ID
<superconductivity>, and ourbigbook renders links correctly for you wherever the output lands.When moving headers to separate pages, it is true that existing links to subheaders will break, but that simply cannot be helped. Large pages must be split into smaller ones. The issue can be mitigated in the following ways:
-S,--split-headers, which readers will eventually understand are better permalinks- JavaScript redirect to split on missing ID, which automatically redirect
condensed-matter-physics#superconductivitytosuperconductivity, potentially hitting a split header if the current page does not contain the HTML IDsuperconductivity.
For OurBigBook Web, this is even more important, as we have dynamic article trees, so every header can appear on top.
If you really want to to use scopes, e.g. enforce the ID of "superconductivity" to be "condensed-matter-physics/superconductivity", then you can use the scope feature. However, this particular case would likely be a bad use case for that feature. You want your IDs to be as short as possible, which causes less need for refactoring, and makes topics on OurBigBook Web more likely to have matches from other users.