OurBigBook
Embed as many external resources such as images and CSS as possible into the HTML output files, rather than linking to external resources.
The use case for this option is to produce a single HTML file for an entire build that is fully self contained, and can therefore be given to consumers and viewed offline, much like a PDF.
Examples of embeddings done:
- CSS and JavaScript are copy pasted in place into the HTML.The default built-in CSS and JavaScript files used by OurBigBook (e.g. the KaTeX CSS used for mathematics) are currently all automatically downloaded as NPM package dependencies to ourbigbookWithout
--embed-resources, those CSS and JavaScript use their main cloud CDN URLs, and therefore require Internet connection to view the generated documents.The embedded version of the document can be viewed offline however.There is however a known bug: KaTeX fonts are not currently embedded, so math won't work properly. The situation is similar as for images, but a bit harder because we also need to fetch the blobs from the CSS, which is likely doable from Webpack:
Examples of embedding that could be implemented in the future:
- images are downloaded if needed and embedded as
data:URLs.Doing this however has a downside: it would slow the page loading down. The root problem is that HTML was not designed to contain assets, and notably it doesn't have byte position indices that can tell it to skip blobs while parsing, and how to refer to them later on when they show up on the screen. This is kind of why EPUB exists: github.com/ourbigbook/ourbigbook/issues/158Images that are managed by the project itself and already locally present, such as those inside the project itself or due tomedia-providersusually don't require download.For images linked directly from the web, we maintain a local download cache, and skip downloads if the image is already in the cache.To re-download due to image updates, use either:--asset-cache-update: download all images such that the local disk timestamp is older than the HTTP modification date withIf-Modified-Since--asset-cache-update-force: forcefully redownload all assets
Keep in mind that certain things can never be embedded, e.g.:
- YouTube videos, since YouTube does not offer any download API