Feedback from @MartijnBraam :

• Add instructions on how to exit the serial console session

Initial draft:

$ picocom /dev/ttyUSB0 -b 115200
...
Press Ctrl+a and Ctrl+x to exit

Suggested formatting improvement:

• Use shell-session block

Just trying to check if does like it the comment - will try to experiment with gh pages on the weekend:

$ picocom /dev/ttyUSB0 -b 115200
...
Press Ctrl+a and Ctrl+x to exit

Added some styling adjustment.
Using shell-session flag does work at least when locally building the gh-page.

See experimentation with a few combinations to check if shell-session is functioning as expected in the code block:

Later changes with some explanations as of what to do if the baud is different between the OS and TowBoot can be done with another PR.

I believe this is good enough for the moment, @samueldr

Hi! 👋

Sorry it took a while to finally review.

About shell-session, with which markdown rendering engine were you testing? How did you end-up deciding to use shell-session?

The Tow-Boot website uses no formatting by default, and AFAICT I'm not sure if it is working for GitHub or not.

I have seen this file linked as supposedly the list of languages known, and I've highlighted a section which seems probably relevant:

• https://github.com/github/linguist/blob/16a7a528ab840dd24188edda671d31881a67e527/lib/linguist/languages.yml#L6265-L6276

Though maybe it's a case where ShellSession is translated to shell-session.

Hi, @samueldr , the suggestion for shell-session came from @MartijnBraam and I think it is a great one.

From what I can see, it doesn't render here in GitHub's comments and I'm not sure if it does when used in GitHub Readme's (I believe it doesn't).
Thanks for the link to github's linguist page!

However, it does render on the deployed TowBoot Github Page as can be seen by the screenshot of a locally deployed version as per the docs here:
#182 (comment)
In the screenshot, you can observe the example of both type of blocks - one using shell-session and two without.

I've used Firefox on my system when viewing the local version at the time - I don't expect it would matter if the end user is on Chromium based browsers.

I haven't looked specifically at the website resources/ Jekyll setup to reference which rendering engine is used or if there is flag allowing shell-session to be rendered - I can just see that it does on the deployed webpage.

So, the renderer allowing shell-session should be defined somewhere in this gem or it's dependencies:
https://github.com/github/pages-gem

Digging a bit further, I've reached a place where I'm struggling to find the options for the highlighter:
https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Base.html#method-i-highlight_code

Or would it be this one? https://github.com/github/linguist/blob/master/lib/linguist/languages.yml#L6272

However, it does render on the deployed TowBoot Github Page as can be seen by the screenshot of a locally deployed version as per the docs here:

The website isn't built using jekyll :)

• Tow-Boot/doc/default.nix

  Line 31 in 00b18a0

  ruby ${./_support/converter}/main.rb src/ $out/

In turn it renders using cmark-gfm

• Tow-Boot/doc/_support/converter/main.rb

  Line 45 in 00b18a0

  "cmark-gfm",

This will pass through the language tag to the block. That part works as expected. The thing that hung me up was how we don't have language formatting for code blocks being done. AFAIUI it would be expected to be done with a script at runtime, and the Tow-Boot website doesn't.

But don't worry. I mainly wanted to understand the reasoning for choosing shell-session, and how it was tested. It won't cause problem for either the GitHub view or the website rendering, so it's okay.

I will rebase/squash the commits as needed, and will add a prefix to the commit titles (doc:). Don't worry about that, it's on me for not providing a contributing guide explaining my preferred commit naming style :).

Hi, sorry it took a while until I got around to handling this PR.

Thank you again!