Add `shell` and `sql-shell` shortcodes

[at055612]

This PR does:

• Upgrade PrismJS from 1.21.0 to 1.28.0
• Adds in the PrismJS command-line plugin (https://prismjs.com/plugins/command-line/)
• Adds shortcode shell for bash type command line input/output (with line continuation support)
• Adds shortcode sql-shell for SQL type command line input/output (with line continuation support)

The following are examples of using shell with a simple fenced block for comparison

## Bash Shell

{{< shell >}}
echo hello
(out)hello
echo goodbye
(out)goodbye
{{< /shell >}}

{{< shell >}}
echo hello \
and \
goodbye
(out)hello and goodbye
{{< /shell >}}

{{< shell "dev" "myhost" >}}
echo hello \
and \
goodbye
(out)hello and goodbye
{{< /shell >}}


```bash
echo hello \
goodbye
```

Which looks like this (note the ability to select just the user input for pasting into an actual shell):

And some SQL examples:

## SQL Shell

{{< sql-shell >}}
select sysdate from dual;
(out)SYSDATE
(out)---------
(out)05-OCT-21
{{< /sql-shell >}}

{{< sql-shell "MySQL>">}}
select sysdate
(con)from dual;
(out)SYSDATE
(out)---------
(out)05-OCT-21
select *
(con)from dual;
(out)DUMMY
(out)----------
(out)X
{{< /sql-shell >}}

```sql
select *
from dual;
```

Which looks like:

The (out) and (con) prefixes can be changed if people can suggest something better.

Note this line in _code.scss. This is a bit of a hack as I am not sure where the colour is coming from for the simple fenced blocks.

background-color: #f8f8f8 !important;

[LisaFC]

Ooh this looks really nice. I'll take a more detailed look (including the mystery colour scheme!).

[at055612]

Am I missing something?

@geriom , Do you have prism_syntax_highlighting enabled? This shortcode relies on a prismJS plugin so you need to be using prism not chroma (the default).

Happy to add some docs on how to use the shortcode and mention the need for prism. However the docsy userguide does not have prism enabled so it will be difficult to demonstrate how is looks when rendered, unless I use screen shots, which is not ideal.

[at055612]

@geriom Documentation added. I have added the documentation without any examples as docsy docs do not have prism enabled. Also included a big warning about needing prism.

[geriom]

@geriom , Do you have prism_syntax_highlighting enabled?

That was it, thank you. It looks great.

Documentation added.

Thanks! I'm taking a closer look to see if I can figure out where is the style for the fenced blocks.

[geriom]

@at055612 The background color for fenced blocks is set by the highlight theme. Switching to a different theme breaks the color consistency in your shortcode because of the hardcoded value.

[at055612]

@at055612 The background color for fenced blocks is set by the highlight theme. Switching to a different theme breaks the color consistency in your shortcode because of the hardcoded value.

By highlight theme I assume you mean

[markup]
  [markup.highlight]
    #style = "tango"
    style = "monokai"

As I understand it these themes are designed for chroma highlighting only. The theme for Prism is baked in when you download the css/js for your chosen theme, e.g. https://prismjs.com/download.html#themes=prism-tomorrow&languages=markup+css+clike+javascript

If I set the hugo/chroma highlight theme to monokai with prism_syntax_highlighting = true then the monokai theme does not render correctly as compared to when prism_syntax_highlighting = false. It seems the chroma theme is fighting with the styling applied by prism.

I was never intending for

background-color: #f8f8f8 !important;

to be left in as I know it is a nasty hack, but did not know how to resolve the background colour difference. I will remove it.

If I try to disable chroma by doing

[markup]
  [markup.highlight]
    style = ""
    codeFences = false

then simple fenced blocks and shell shortcodes now have the same background colour however the simple fenced block now loses the highlight class (that I assume chroma adds) but this then breaks styling like the border and width that rely on the highlight` class. i.e.

I have just pushed some changes to _code.scss and the (sql-)?shell shortcodes that hopefully fixes it when chroma is disabled as above. Happy to change things if there is a better way. Not sure I full understand how pygment/chroma/prism all work together.

[at055612]

With the latest changes it now looks like this:

With chroma

prism_syntax_highlighting = false
[markup]
  [markup.highlight]
    style = "tango"

With prism

prism_syntax_highlighting = true
[markup]
  [markup.highlight]
    style = ""
    codeFences = false

Note the slight difference in bg colour between chroma and prism.

[polarweasel]

I don't suppose there's any way to integrate this logic into normal fenced blocks, is there? We've got logic now to strip prompts from copied commands in our docs site, so prompt-detection isn't too hard, but continuation is a bit more of a hassle.

Still, the tradeoff of once-in-a-while Docsy code maintenance complexity vs the daily pain of writing code blocks like this is something very much worth considering.

[at055612]

I don't suppose there's any way to integrate this logic into normal fenced blocks, is there? We've got logic now to strip prompts from copied commands in our docs site, so prompt-detection isn't too hard, but continuation is a bit more of a hassle.

Still, the tradeoff of once-in-a-while Docsy code maintenance complexity vs the daily pain of writing code blocks like this is something very much worth considering.

@polarweasel Not sure about the integration with normal fenced code blocks. I think that is Hugo rather than Docsy that handles that and the fact that my shortcode relies on PrismJS (which is no standard in Hugo) complicates things. One of the maintainers may be able to comment on that front. Personally I think it may complicate things for simple fenced blocks and give people prompts then they don't want them.

Potentially this shortcode could be changed to strip prompts and add (out) prefixes from the shortcode content so you can just paste in something straight from the shell. Something like this (which assumes a simple prompt of $.

{{ $content := trim (.Inner | default "") "\n " }}
<!-- Prefix all lines with (out) -->
{{ $content = replaceRE "(^|\n)([^\n]+)" "${1}(out)${2}" $content }}
<!-- Remove the (out) prefix and prompt/continuation from any prompt/continuation lines -->
{{ $content = replaceRE "(^|\n)[(]out[)][$>] " "${1}" $content }}
.....
    {{- with $content -}}
    <code class="language-{{ $language }}">{{- . -}}</code>
    {{- end -}}

would convert

$ echo hello \
> goodbye
hello goodbye

into

echo hello \
goodbye
(out)hello goodbye

Would likely need additional args to allow setting of the prompt, however if people are using fancy themed prompts (e.g. oh-my-zsh) then the regex would become very nasty.

In terms of the ease of using a short code like this, code snippets in your editor are a big help. I use vim with ultisnips (and some custom snippets for the various shortcodes I use) so adding a shell shortcode block is just typing hcli<tab><type or paste content><tab>