Exclude veiled artifacts from navigation in Guise Mummy.

Description

Guise Mummy needs to recognize one or more asset directories as "veiled" and exclude them from regenerated navigation lists. Assets are usually things such as CSS files, JavaScript files, and images; and they are usually stored in dedicated directories. But we don't want those directories to be included in navigation.

Therefore Guise Mummy will introduce the concept of a "veiled" artifact, defined as:

veiled: A resource that is available to be served to the user agent if access directly, but is not part of the normal navigation tree.

It is noteworthy the things that this definition does not say:

  • It does not say that veiled artifacts are not included. Veiled artifacts appear in the target just like any other resource.

  • It does not say that veiled artifacts are not described. Images for example may have description metadata, perhaps derived from sidecar files or even internal EXIF information.

  • It does not say that veiled artifacts are not processed. A Markdown file in an assets directory will still be turned into an HTML file, for example. (A file that is not processed will be referred to as a static file.)

(While the obvious use of a veiled artifact is to hide an asset, it's best not to presuppose why the user wants to "hide" an artifact. The word "shrouded" is also interesting, but it is best to reserve that word for a stronger type of hiding, such as generating a robust random sequence for the artifact URL. This may be done in the future.)

There are several possible approaches to denote an veiled artifacts. The easiest and most understandable way would be to have some directory subtree devoted to assets. The next question is how one designates that directory.

One approach would be to say that any directory prefixed with an underscore _ denotes an asset directory. But Jekyll and Sass generally use this pattern to mean source files that are not included in the output at all. This might be confusing.

Another approach would be to use a convention, e.g. "the assets subdirectory is always considered an asset subtree". Of course this could be reconfigured, but it might frequently clash with existing needs, e.g. having a subpage talking about company assets (rather than web assets). Another drawback is that some research might be needed even to get started, to find out that you can hide things from navigation flow using the assets directory. Granted one has to do research anyway to learn about the src/site directory, but the fewer things to research the better.

Initially identifying assets is important in order to hide e.g. the CSS and JavaScript directories and files when regenerating navigation lists.

Reviewing these considerations, it seems that using an underscore _ prefix to denote non-navigable items is the most flexible and approach. The two biggest drawbacks seem to be:

In the end the approach taken by this ticket is to use a _ prefix to indicate "veiled" artifacts or artifact trees. The actual use of the "veiled" designation in generating navigation lists has been moved to the individual page mummifier. (This is because other mummifiers, such as Sass mummifiers, might have different rules for what underscores in the filename mean within a subdirectory or whether there is such a thing as "navigation" for that type of artifact.) It's not unreasonable to suppose that in the future the _ prefix will be able to be configured, but for now there is no pressing need to do so.

Environment

None

Assignee

Garret Wilson

Reporter

Garret Wilson

Labels

None

Fix versions

Priority

Critical
Configure