Question about highlighting code fragments

[nzubair]

Issue Details

Can you please advise what's the proper way to highlight code fragments?

I've seen this:

```
PS C:>Get-Process
```

and

```powershell
PS C:>Get-Process
```

I've seen some comments (can't recall where) that due to PS C:\> part, this is not a powershell code fragment. Therefore it should not be highlighted by ```powershell`, rather by simple three backticks.

Can you advise what is preferred?

Version(s) of document impacted

• Impacts 5.1 document
• Impacts 5.0 document
• Impacts 4.0 document
• Impacts 3.0 document

[wsmelton]

Markdown formatting allows you to use the powershell keyword, it won't necessarily highlight the prompt section but the remaining code (e.g. Get-Process) would be highlighted appropriately.

PS C:> Get-Process

PS C:> Get-Process

It works the same way when you post code in issues on GitHub.

[nzubair]

I understand that. My question was whether or not the PowerShell-Docs team has a preference.

[nzubair]

Found the comment. It was @vors who made this comment: #895 (comment)

[HemantMahawar]

IMHO, once you tag the code with block with powershell ( ```powershell) , there is no need for PS C:> prompt as it does appropriate highlighting of PowerShell code. Also, it makes copy-paste easier without the need to copy/remove the PowerShell prompt.

[joeyaiello]

I agree with @HemantMahawar, but unfortunately that doesn't work for when cmdlet reference examples get turned into MAML (which is why we probably shouldn't remove them).

[HemantMahawar]

Good point @joeyaiello about maml help /cc: @zjalexander @juanpablojofre @eslesar

[zjalexander]

@eslesar and @juanpablojofre and I have all discussed this, the consensus is:

Do NOT use PS C:>

DO use ```powershell.

Many of our docs today do not conform to this since they were ported forward. Many of our docs will probably not conform to this in the future, and those are bugs we should correct.

I also discussed the MAML issue with @joeyaiello and we can resolve this with "make sure to put an extra line break between a command and command output ".

This raises a few other issues - hey, don't we need a style guide (#15) ? can we get rid of extraneous linebreaks that have been created through the years (#1025)?

@nzubair - does this answer your question fully?

[nzubair]

Yes it does. Thank you.

[nzubair]

Was playing around with this and what I've found that removing PS C:> seems to make the example hard to read.

PS C:> "abc" -eq "abc"
True

vs.

"abc" -eq "abc"

True

[exchange12rocks]

Maybe, the better option would be to remove the prompt from a multi-line commands while leaving it at single-line examples.

[wsmelton]

Well formatting wise so folks can follow what is output and what is code it would be best to just break them up for the examples. If you kept the "PS C:>" it was a better indicator of what command was actually being shown.

Code:

"abc" -eq "abc"

Output:

true

[nzubair]

That's sensible. .Net folks seem to be doing something similar (https://docs.microsoft.com/en-us/dotnet/articles/csharp/tour-of-csharp/index). However, they are doing some post-processing when it's published live, as opposed to doing everything in MarkDown.

That being said, there are quite a few example-heavy documents, where this format will not work. It becomes confusing and unreadable quickly, especially if there is no additional formatting employed.

Just looking at MarkDown docs, take a look at the following two docs (excerpts from about comparison operators)

Current formatting: https://github.com/nzubair/TestRepo/blob/master/test1.md
New formatting: https://github.com/nzubair/TestRepo/blob/master/test2.md

Style guidelines need to be established, which @zjalexander alluded to earlier. Seems like there hasn't been any activity on that issue for a while.

[exchange12rocks]

.Net folks do not include output as a real console output - they just insert it in comments - that makes their life easier in a way..

[nzubair]

Not in the page I linked above. They're actually using

```console
Hello, World
```

[zjalexander]

@nzubair test2.md would throw a platyps error with the current schema because it only expects 1 version block: https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md#version-200

related: PowerShell/platyPS#243

anyway, thanks for all the feedback everyone, i'm going to round up some of my team members and see how they feel.

[nzubair]

test2.md was @wsmelton's suggestion. I just wanted to see how it would come out.

I've been working on some of the about_* topics. However, I will hold off until there is some clarity on this.

Thank you.

[zjalexander]

One idea @joeyaiello had is to use comment blocks for output to prevent weird syntax highlighting issues:

Get-Variable $true
#Name                           Value
#----                           -----
#true                           True

[rjmholt]

Another thing I've seen -- which very probably can't be done with pure markdown, but might be worth mentioning anyway -- is using the CSS before selector for shell prompts: an example from GitHub shows a bash prompt with a $ character, but it can't be selected.

[zjalexander]

I believe this issue was resolved by #1095, please open a new issue if that's not accurate.