This 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
When linking to Superconductivity from an external page such as
statistical-physics.bigbyou write just
<condensed-matter-physics#superconductivity>. OurBigBook then automatically trakcs where superconductivity is located and produces
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.htmlotherwise page loads for
condensed-matter-physics.htmlwould 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:
--split-headers, which readers will eventually understand are better permalinks
superconductivity, potentially hitting a split header if the current page does not contain the HTML ID
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.