This is a list of project announcements such as new features sorted in cronological order, from the newest to oldest.
Significant entries will have a corresponding announcement on the following official accounts:
Docs: Section "Horizontal rule (\Hr)"
Before the rule.

More before the rule.


After the rule.

More after the rule.
which renders as:
Before the rule.
More before the rule.

After the rule.
More after the rule.
We're experimenting with a more traditional and boring "dark" theme than the green on black classic previously used.
Readability is probably slightly better, though it is hard to measure these things. It is quite possible that the change matter much more for some people than others who have different eye sight phenotypes.
Perhaps the most important outcome of this is that it will greatly reduce the endless complaning from the community. Though perhaps that was a feature rather than a bug?
Beyond the theme change, many other changes were made. Many of those improvements feel like undisputable upgrades, e.g.:
  • headers are not colored differently from regular text
  • table borders are less visible
  • navbar and footer are more discrete and readable
The CSS code was also refactored and it is not much easier to make broad color changes such as hese in the future, as color constants are not more closely grouped, and fewer constants are now used.
Large parts of this change were pushed forward by sidstuff who contributed a several code snippets and ideas to it.
Video 1.
Intro to the OurBigBook Project
. Source.
It is now possible for admins pin an article to the homepage. The initial use case is to help with new user onboarding. Documentation: pinned article.
Previously we would only create an entry in the _file output directory for headers marked wiht the \H file argument.
For example the file file_demo/hello_world.js in this repository has an associated header with the file argument in our README.bigb :
= file_demo/hello_world.js

An explanation of what this text file is about.

Another line.
As a result, when doing a split header conversion, it would get both:
On the other hand, the test file file_demo/nofile.js has no such associated header in the source code.
Before this change, file_demo/nofile.js would only get an _raw directory entry under _raw/file_demo/nofile.js and not _file entry. But now it also gets both.
The advantages of a _file entries over _raw entries are as follows:
  • _file entries can have metadata such as:
    • OurBigBook content associated to them when they have an associated _file header. For example at file_demo/hello_world.js we can see the rendered text:
      An explanation of what this text file is about.
      Another line.
      Of course, in that case, they would also get the _file entry even before this update. However, this update does allow for a smooth update path where you can first link to the _file entry from external websites, and then add comments as needed later on without changing URLs.
    • Google Analytics and other features via ourbigbook.liquid.html
  • _file always shows on static website hosts like GitHub Pages, since they are just HTML pages. This is unlike raw files which may just get downloaded for unknown extensions like .bigb rather than displayed on the browser: _raw files are downloaded rather than displayed in browser for certain file extensions on GitHub Pages
This change is especially powerful following Always show large text files on _file split headers.
Because we now have _file entries for every single file, we have also modified _dir directory directory listing pages to link to _file entries as those are generally more useful than _raw which is what they previously linked to. And you can always reach _reaw_ from the corresponding _file is needed. Example: docs.ourbigbook.com/_dir
Previously, large files with an \H file argument associated to them would show a message
index.js was not rendered because it is too large (> 2000 bytes)
rather than the file contents both on their split and non-split versions, e.g.:
Now, the split version docs.ourbigbook.com/_file/index.js alwayws shows the full text file.
When not in split mode, limiting preview sizes is important otherwise multi-header pages might become far too big. Ideally we would have found a way to reliably use iframe + loading="lazy" to refer to the file without actually embedding it into the page as we do for images, but we haven't managed to do that so far.
This allows us to now see files that were previously not visible anywhere on the rendered HTML without download due to _raw files are downloaded rather than displayed in browser for certain file extensions on GitHub Pages.
The main focus was the Table of contents rendering, which had a lot of redundant stuff. Headers were the next largest gain.
The main techniques used to reduce size were:
  • auto-generate a few elements on-the-fly with JavaScript for on-hover effects, but only if it doesn't affect SEO and readability when JS is turned off
  • use a lot more CSS ::after and ::before to avoid embedding repetitive icons multiple times on the HTML
After this changes, the rendered size of cirosantilli.com fell from 216 MiB to 156.5 MiB, which is kind of cool!
In previous updates we added insane topic links which allow you to write #mathematics to link to OurBigBook Web topics such as: ourbigbook.com/go/topic/mathematics
The outcome of that however is that it is also easy and correct to create links to topics that don't yet exist on the OurBigBook Web instance.
To make this nicer, we've unconsciously copied Wikipedia once again, and added a "Create an article for this topic" link
For example, currently OurBigBook.com the topic "Endoplasmatic Reticulum" does not have any articles on it. So if you created a link <#endoplasmatic reticulum>, it would redirect you to: ourbigbook.com/go/topic/endoplasmic-reticulum
Previously, this would show "Topic does not exist". But now it shows a button that opens the new article editor with pre-filled title "Endoplasmatic reticulum". The title choice is only a heuristic as it can't know the correct capitalization, but it covers most cases corectly by default and can be modified manually as needed.


  1. Publicity
  2. Developing OurBigBook
  3. OurBigBook Project