Feature: Recognize [console] and [bash session] as cram test code blocks

[jonahbeckford]

Root Problem

The ```sh``` code blocks that are supported and documented for cram tests are not actually sh blocks.

Context

A sh block is:

cd .
ls --help

A console block (at least in GitHub Flavored Markdown) is:

$ cd .
$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.
...
  -T, --tabsize=COLS         assume tab stops at each COLS instead of 8
  -u                         with -lt: sort by, and show, access time;
                               with -l: show access time and sort by name;
                               otherwise: sort by access time, newest first
  -U                         do not sort; list entries in directory order
  -v                         natural sort of (version) numbers within text
  -w, --width=COLS           set output width to COLS.  0 means no limit
  -x                         list entries by lines instead of by columns
  -X                         sort alphabetically by entry extension
  -Z, --context              print any security context of each file
  -1                         list one file per line.  Avoid '\n' with -q or -b
      --append-exe           append .exe if cygwin magic was needed
      --help     display this help and exit
      --version  output version information and exit

But labeling console blocks as sh blocks misrenders the block:

$ cd .
$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.
...
  -T, --tabsize=COLS         assume tab stops at each COLS instead of 8
  -u                         with -lt: sort by, and show, access time;
                               with -l: show access time and sort by name;
                               otherwise: sort by access time, newest first
  -U                         do not sort; list entries in directory order
  -v                         natural sort of (version) numbers within text
  -w, --width=COLS           set output width to COLS.  0 means no limit
  -x                         list entries by lines instead of by columns
  -X                         sort alphabetically by entry extension
  -Z, --context              print any security context of each file
  -1                         list one file per line.  Avoid '\n' with -q or -b
      --append-exe           append .exe if cygwin magic was needed
      --help     display this help and exit
      --version  output version information and exit

Proposed Fix

Recognize the tokens console and bash session (GitHub Flavored Markdown)) in addition to sh as cram test code block tokens.

Hacky mitigation today

https://github.com/diskuv/diskuvbox/blob/62da4c3fc269bb707a5d71752e673baa1e207d00/dune#L9-L34

[NathanReb]

I think it's not properly documented atm but there are labels you can use to force the type of a block in MDX. In that case you could force MDX to interpret those blocks as cram blocks.

You should be able to write:

That's a cram block underneath:

<!-- $MDX cram -->
```console
...
```

Explicitly stating the type of the block is good practice as it helps MDX with error reporting as you know you and MDX agree on the type of block, which might not be the case when you let MDX guess it from the language token and the syntax inside the block.

We can also add support for those language tags in cram blocks but in the meantime I'd advise you use this explicit declaration approach!

[jonahbeckford]

Thanks! I'll do that.

But that approach has a problem ... all code blocks

<!-- $MDX cram -->
```console

are changed to the following during ocaml-mdx test or (mdx (files README.md)):

<!-- $MDX cram -->
```sh

[NathanReb]

Ah, that's a bug indeed! Sorry for the inconvenience, we'll look into it!

[brendanzab]

Any word on a fix for this? It’d be nice to get proper syntax highlighting on Github by using console instead!