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 powershell code fences where appropriate #1511

Closed
chenrylee opened this issue Aug 4, 2017 · 15 comments
Closed

Add powershell code fences where appropriate #1511

chenrylee opened this issue Aug 4, 2017 · 15 comments
Labels
Pri3 Priority - Low

Comments

@chenrylee
Copy link
Contributor

The Powershell docs have been migrated to new place, and now they all became good-look.
I have read some articles, and found the code blocks are not highlighted.
Indeed, this feature is supported.
I picked a block in an article, it's the original style:

PS> Get-Command -Name Clear-Host

CommandType     Name                            Definition
-----------     ----                            ----------
Function        Clear-Host                      $spaceType = [System.Managem...

if we add the language tag, it shows:

PS> Get-Command -Name Clear-Host

CommandType     Name                            Definition
-----------     ----                            ----------
Function        Clear-Host                      $spaceType = [System.Managem...

Yes, just add powershell following the first 3-grave mark.

  ```powershell

Can you please update all code blocks within the articles?

@joeyaiello joeyaiello changed the title Highlighting Code Block Add powershell code fences where appropriate Aug 8, 2017
@joeyaiello
Copy link
Contributor

We do this generally as we see it. Unfortunately, the syntax highlighting doesn't come out too well in examples like yours where there's output, so that might be why you're not seeing it in certain places.

@kiazhi
Copy link
Contributor

kiazhi commented Aug 14, 2017

Shouldn't the PS:\> be excluded.

Example below:
```powershell
Get-Command -Name Clear-Host
```
```text
CommandType Name Definition
----------- ---- ----------
Function Clear-Host $spaceType = [System.Managem...
```

Output as below:

Get-Command -Name Clear-Host
CommandType     Name                            Definition
-----------     ----                            ----------
Function        Clear-Host                      $spaceType = [System.Managem...

@zjalexander
Copy link
Contributor

that's what I have in the Style Guide, yeah.

@sdwheeler
Copy link
Contributor

@chenrylee @zjalexander Now that we have moved the documentation to docs.microsoft.com, we can leave the PS:\> prompts in the examples. The copy button on the frame of the text box will remove the prompts when it copies the text to the clipboard. This allows the code to be more 'paste-able' to the command line.

@kiazhi
Copy link
Contributor

kiazhi commented Aug 18, 2017

Hi @sdwheeler,

Its great to know that it omit PS:\> in the examples, but does it also omit PS C:\> in the examples too? Reason for that question is that there are about ~10000 results in 1437 files that contains PS C:\> in examples in this PowerShell-Docs repo.

@sdwheeler
Copy link
Contributor

@kiazhi
It works on any inside a markdown code fence.

@zjalexander
Copy link
Contributor

So as per the style guide:

  • Omit PS C:/>

The style guide does NOT have the following:

```powershell
Get-Command -Name Clear-Host
```
```text
CommandType Name Definition
Function Clear-Host $spaceType = [System.Managem...
```

Given how docs is rendering it, we do prefer that and I will update the style guide. However, instead of ```text we can use ```output which Docs recommends.

We should fix this as we touch individual articles.

@zjalexander zjalexander self-assigned this Aug 30, 2017
@zjalexander
Copy link
Contributor

PowerShell/platyPS#294 there is also a related PlatyPS ask to insert this automatically.

@MSAdministrator
Copy link
Contributor

@zjalexander Is this up for grabs? I can take this and run through the MDs and submit a PR

@sdwheeler
Copy link
Contributor

@MSAdministrator This is up for grabs. Please avoid the About_ topics. These were recently reformatted to meet the requirements of changes to our tool chain. Also please read the recently updated Contributors Guide, especially https://github.com/PowerShell/PowerShell-Docs/blob/staging/contributing/FORMATTING-CODE.md.

Thanks for helping out.

@MSAdministrator
Copy link
Contributor

In progress, I plan doing PowerShell 3.0 to 6.

@sdwheeler sdwheeler added in-progress Tag - issue is being worked on by someone and removed Up-for-Grabs labels Jan 12, 2018
@MSAdministrator
Copy link
Contributor

@sdwheeler No problem! Quick question, should I commit each MD and then PR a branch for each version? Or commit each MD and do 1 big ol' PR? or something else? :) Almost done with 3.0

@sdwheeler
Copy link
Contributor

Minimize the commits but number of commits is not that important. Do a branch for each topic. My suggestion is this - say you are updating Get-Content.md. Update all versions (3/4/5/5.1/6) of Get-Content.md. The updated files can be one or more commits to your branch. PR that branch. See #1969 for an example PR like this.

@MSAdministrator
Copy link
Contributor

@sdwheeler Will do! Thanks for the clarification!

@MSAdministrator
Copy link
Contributor

@sdwheeler An example of my changes across all the docs is in #2070

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Pri3 Priority - Low
Projects
None yet
Development

No branches or pull requests

6 participants