News / Automatically create `_file` pages for every file

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 index.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 _file output directory page at path _file/file_demo/hello_world.js file_demo/hello_world.js
a _raw directory page at path _raw/file_demo/hello_world.js file_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:

_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

News / Automatically create _file pages for every file

 Ancestors (4)

News / Automatically create `_file` pages for every file