Code blocks, continued...

[drwelby]

This extension comes at a perfect time for me because I have been working on documentation systems for the last 4 months. Additionally I can put this extension into the top-level STAC Collections of Maxar Open Data. Since STAC Browser is a common entry point for ODP users having a working "Examples" section pointing to our documentation would be helpful for humanitarian mappers who may be new to cloud native geospatial data.

In reviewing documentation systems big and small, very few sites have standalone code examples. Typically you would see this approach where a documentation team wants to be able to run CI/CD testing against code snippets and then inserts the snippets into their textual documentation. The bulk of documentation in the wild tends towards more explanatory text with interspersed code blocks. While some teams use Jupyter as an authoring environment, these are almost always rendered to HTML.

For example, in the Maxar ARD documentation we only have 1 Python file, <10 Jupyter Notebooks (available for download but also rendered as documentation pages), and hundreds of HTML pages.

Therefore, it seems like flagging "containers" is backwards and we should only flag the minority case when an example is renderable as a code block instead. We could be explicit about this but this seems feels like it leans too heavily to the presentation side versus the content side.

One idea is to keep examples in Links as documents that follow the broader concept of a hypertext protocol, and move code examples to Assets with the roles example and/or code-block. This seems to fit the description of an Asset as any 'sidecar' files that are related and help a client make sense of the data.

A simpler alternative would be that links to documention could use the describedby rel, and we introduce example to only handle cases where the linked object is a standalone example that would benefit from syntax highlighting.