Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add shell and sql-shell shortcodes #1012

Open
wants to merge 20 commits into
base: main
Choose a base branch
from

Conversation

at055612
Copy link
Contributor

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):

image

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:

image

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
Copy link
Collaborator

LisaFC commented May 18, 2022

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

@deining deining added the shortcodes Hugo shortcodes label May 19, 2022
Copy link
Collaborator

@geriom geriom left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great! Unfortunately it's not working for me. This is what I get:

shell-shortcode

Am I missing something?

Can you please add a new section in the Shortcodes docs explaining how to use this shortcode.

@at055612
Copy link
Contributor Author

at055612 commented Jun 10, 2022

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
Copy link
Contributor Author

@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 force-pushed the add-shell-shortcodes branch from 56c0689 to 81db00d Compare June 15, 2022 15:30
@geriom
Copy link
Collaborator

geriom commented Jun 15, 2022

@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
Copy link
Collaborator

geriom commented Jun 15, 2022

@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
Copy link
Contributor Author

@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.
image

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
Copy link
Contributor Author

at055612 commented Jun 16, 2022

With the latest changes it now looks like this:

With chroma

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

image

With prism

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

image

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

Also change the card styling to use .highlight or .code-toolbar so it
works with prism or chroma
@polarweasel
Copy link

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
Copy link
Contributor Author

at055612 commented Jul 5, 2022

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>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
shortcodes Hugo shortcodes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants