Shell not indicated in some examples, missing alternative shell solutions

[Simran-B]

What article on docs.github.com is affected?

For instance, Actions - Workflow commands: Setting an environment variable does not say that the examples are bash specific. They won't work as-is in cmd or powershell on Windows.

What part(s) of the article would you like to see updated?

• Tell the user what shell an example is for if it's not compatible with all standard terminals
• Ideally provide examples for other shells as well

Additional information

In Workflow syntax for GitHub Actions there is actually a great example of how it should be:

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[Simran-B]

On second thought, I think it would make more sense to have tabs similar to the platform specific content, but render the tabs for each example group instead of once at the top of the page:

Changing the tab should be reflected by all other shell-specific examples. I'll try to implement a prototype. I think it will require nested Liquid tags? Let me know if you can think of another way.

### About workflow commands

{% shelltabs %}

{% bash %}

`echo "{name}={value}" >> $GITHUB_ENV`

{% endbash %}

{% pwsh %}

`echo "{name}={value}" | Out-File -Append -FilePath $env:GITHUB_ENV -Encoding utf8`

{% endpwsh %}

{% cmd %}

`chcp 65001 > nul & echo {name}={value} >> %GITHUB_ENV%`

{% endcmd %}

{% endshelltabs %}

[Simran-B]

Hard-coding it to shells might actually allow this to be implemented without nesting tags, but I'm in favor of a generic tab widget solution. I believe that it will require a group name to correctly update related example groups, and to avoid switching tabs of unrelated groups with an equally named tab. Something along:

{% tabs "shell" %}
{% tab "Bash" %} ... {% endtab %}
{% tab "PowerShell" %} ... {% endtab %}
{% tab "Windows `cmd`" %} ... {% endtab %}
{% endtabs %}

[janiceilene]

Thanks for opening an issue @Simran-B! I'll let the @github/docs-content-ecosystem review 💛

[lucascosti]

Thanks a lot for these suggestions, @Simran-B!

• Tell the user what shell an example is for if it's not compatible with all standard terminals
• Ideally provide examples for other shells as well

Although Linux/bash is our default when showing examples (the vast majority of Actions CI is done using Linux runners), we can do a lot better at explaining and showing this in our examples.

On second thought, I think it would make more sense to have tabs similar to the platform specific content, but render the tabs for each example group instead of once at the top of the page

This is a good idea, but I don't think we have plans at the moment to expand the 'tabs' we have in the documentation. This will require some engineering effort to support additional liquid tags, and it's not currently on our roadmap. At the moment, we only support operating system tags.

I've triaged this as an enhancement issue, so anyone can pick up and add explanatory text/headings to examples that require some explanation on the appropriate shell/OS 🙂

[Simran-B]

@lucascosti Thanks for the positive feedback!

This will require some engineering effort to support additional liquid tags, and it's not currently on our roadmap.

I'm looking into an implementation of general purpose tabs, but I'm uncertain about several aspects of the documentation system and hit a few problems. Is there anyone I can talk to about the architecture and the components of the system? There seems to be very little documentation about the documentation system. Shopify's liquid implementation in Ruby and its documentation is somewhat helpful, but I'm unsure how closely liquid.js follows its design.

• https://github.com/docs/render-content
• https://github.com/docs/liquid
• https://github.com/github/docs/tree/main/lib

[lucascosti]

Is there anyone I can talk to about the architecture and the components of the system?

I'll tag in @github/docs-engineering for this, and if they're open to receiving contributions 🙂

[himanshu211raj]

Is there anyone I can talk to about the architecture and the components of the system?

I'll tag in @github/docs-engineering for this, and if they're open to receiving contributions 🙂

I am here and now I am always ready to contribute in open source. But due to the reason that I am a beginner so I have limited knowledge and day by day I will improve my skills to contribute more and more to open source.