Feature: styled terminal output screenshot

[cristianofromagio]

Is your feature request related to a problem? Please describe.

The screenshots of the terminal output, although it serves it purpose (to display a real example), seems a little out of place. To attribute a familiar design to it (like a window frame) might be easier for the reader to situate itself.

Describe the solution you'd like

We may use a tool like https://carbon.now.sh/ to generate images from the text in the current screenshots. We can customize font family, font size, colors and even syntax highlight (although for terminal "output" it might be a bit wrong when using ie. bash ou powershell as language option).

Additional context

A simple example for:

root@docker:~# docker version
Client:
 Version:           20.10.7
 API version:       1.41
 Go version:        go1.13.8
 Git commit:        20.10.7-0ubuntu1~21.04.2
 Built:             Fri Oct 1 03:50:45 2021
 Os/Arch:           linux/amd64
 Context:           default
 Experimental:      true

Server:
 Engine:
  Version:          20.10.7
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.13.8
  Git commit:       20.10.7-0ubuntu1~21.04.2
  Built:            Fri Oct 1 02:50:01 2021
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.5.2-0ubuntu1~21.04.3
  GitCommit:
 runc
  Version:          1.0.0~rc95-0ubuntu1~21.04.2
  GitCommit:
 docker-init:
  Version:          0.19.0
  GitCommit:

Currently

Carbon generated

If you consider replacing the images like so, I volunteer to generate them and PR the new ones.

[bobbyiliev]

Hi @cristianofromagio this is a great idea! Would be awesome if you had the time to do that!

[cristianofromagio]

Hello @bobbyiliev, it is me again! Sorry for the super late get back to this feature but you know, life gets in the way sometimes...

Anyways, I've been tinkering with a solution for this and now gonna list what I've managed to get sorted. First of all, this was really fun to research and build until now!

Goals

I've set that this feature should at least be able to be somewhat automated, meaning we should be doing the bare minimal of manual setting.

• gather text from current used images (my first thought was to use OCR)
• automatically generate all images from collected text outputs
  • with syntax highlight and "terminal" window titlebar
• optimize generated images

Tested solutions

• Using kinda of an undocumented API (previously here) from Carbon to automatically generate all highlighted images
  • I iniatially used this feature to learn some python, so I looked through the said API source code to make requests and get all images created. I've managed to get some results back in Oct/2021, but it seems they changed the API because my script doesn't work anymore.
  • The main problem from the beginning was that the command output "code" (or even the command itself) was not properly highlighted.

Open to see some outputs from Carbon

 

• From Carbon not working out, I've come across Torchlight on the Laravel Docs website footer. After reading the docs for a bit, I found they had a themsaid/ibis plugin to automatically convert markdown code blocks from e-book content files into highlighted code blocks on the PDF output.

  • They have a free tier plan for "Personal / Open Source" usage, so I thought they could be used here.
  • To use it, I simply run the images through an OCR (GoOCR and OCR Space) to get the output text from the content image files, then replaced the images on the markdown files with a code block with shell as language syntax.
  • After getting it to work, a problem with it was sometimes it wouldn't properly style the code blocks (background-color), although it properly highlighted all of the code blocks on content files, even the single lines we didn't account for.
  • The main "problem" is that it is just a code syntax highlighter. I've tried to append an element inside the generated HTML content before the PDF creation on ibis build to display the terminal window bar but never got to get it working, mainly because of mPDF limitations (mPDF being the package ibis uses to transform HTML into PDF). I tried CSS solutions like pseudo elements, border-images and background-images, all of which had little to no support.

• The styling issues faced from Torchlight-ibis made me look for other code syntax highlight solutions, and that is when I ended up finding PrismJS.

  • After setting up a little project using Marked + Prism I could finally get to see a code highlighted with a window titlebar.
  • The problem was that I was unable to implement this tooling into the ibis project because it uses league/commonmark for markdown rendering and scrivo/highlight.php for code syntax highlight (both from spatie/commonmark-highlighter), in other words, it was a PHP tooling, not a JS one.
  • Because of that inability to embed the highlighted code into the rendered HTML (as we get from using Torchlight), I set up a little script to save a image from the Marked+Prism code styled+highlighted blocks. The only problem with it was we now lose the ability to copy/select the commands and text from the images. To bypass this, I thought of instead of saving the code blocks nodes as a PNG image, what if I could save it as SVG and embed it into the content? And was then that I discovered the DOM to SVG library. I've saved all code blocks to SVG files and embed them into the content files, replacing the old images. But there was just one problem: mPDF (yep, this one again). mPDF doesn't support some SVG properties exported by dom-to-svg, so the images where all messed up on the PDF output. After that I would go on a quest to replace ibis's mPDF dependency with something else (TCPDF) only to find out its CSS support was even lesser than mPDF.
  • One of the main points that made PrismJS attractive was the command-line plugin. It displays the command output with a specific layout, something other solutions didn't have.

Open to see some outputs from Prism

  

Suggestions

After all this report, what I got to say is that I don't know how to finish this feature. My main suggestion is that we generate the terminal output images using the Prism project I made, replace the old images with the new styled ones and then run the PDF through PDF OCR so we can have the styling without losing the functionality of selecting the text.

My question now is: what do? How can we finish this feature? I'm gonna need some help with this. I could make the Marked+Prism little project available or incorporate it inside the project. Or just create the images and we get going. What do you think is the best for the project? @bobbyiliev

And again, sorry for the late feedback. This was really fun to piece together!

[bobbyiliev]

You are an absolute legend @cristianofromagio! Thank you so much for putting this together! I will use this as a blueprint and take it from here!