OurBigBook
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:
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
{file}
An explanation of what this text file is about.
Another line.As a result, when doing a split header conversion, it would get both:
- a
_fileoutput directory page at path_file/file_demo/hello_world.jsfile_demo/hello_world.js - a
_rawdirectory page at path_raw/file_demo/hello_world.jsfile_demo/hello_world.js
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:_fileentries can have metadata such as:- OurBigBook content associated to them when they have an associated
_fileheader. For example at file_demo/hello_world.js we can see the rendered text:
Of course, in that case, they would also get theAn explanation of what this text file is about.Another line._fileentry even before this update. However, this update does allow for a smooth update path where you can first link to the_fileentry from external websites, and then add comments as needed later on without changing URLs. - Google Analytics and other features via ourbigbook.liquid.html
- OurBigBook content associated to them when they have an associated
_filealways shows on static website hosts like GitHub Pages, since they are just HTML pages. This is unlikerawfiles which may just get downloaded for unknown extensions like.bigbrather than displayed on the browser:_rawfiles 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/_dirPreviously, large files with an
rather than the file contents both on their split and non-split versions, e.g.:
\H file argument associated to them would show a message
index.js was not rendered because it is too large (> 2000 bytes)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
::afterand::beforeto 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/mathematicsThe 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-reticulumPreviously, 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.
