It looks like you may want to code escape occurrences of dotnet inclusing the first line.

@markekraus RE code escpaping dotnet - done. PR update coming soon.

/cc @anmenaga This PR has some commonalities with #5096.
@rkeithhill You used the PR number in the PR description. Can you please correct it to the corresponding issue number?

@daxian-dbw RE PR # - fixed.

@markekraus RE using powershell formatting, can you look at the MD in view mode. It seems GitHub doesn't do a particularly great job at syntax highlighting PowerShell script. Note the command to add the PowerShellStandard.Library package - the version number is highlighted wrong. Ditto with the command to add a global.json file and:

cd bin/Debug/netstandard2.0

I'm considering removing the powershell syntax directive from these code blocks.

@rkeithhill that's because it should be Set-Location 😉

for the ones that are calling non-PowerShell commands (like dotnet), you could try bash syntax. for the ones that are heavy PowerShell some syntax highlighting is better than none. But you could always make them "proper" powershell by avoiding aliases and quoting strings

Set-Location "bin/Debug/netstandard2.0"
Import-Module "./mymodule.dll"
Write-TimestampedMessage "Test message"

or split them out:
(bash)

cd bin/Debug/netstandard2.0

(pwsh)

Import-Module ./mymodule.dll
Write-TimestampedMessage "Test message"

but together like this:

cd bin/Debug/netstandard2.0

Import-Module ./mymodule.dll
Write-TimestampedMessage "Test message"

@markekraus No one but n00bs quote paths unless there's a space in the path or they tab-complete a path with spaces. And "some" power users will escape a space if there's only one instead of quoting the path. :-) Ditto for Set-Location, most folks use the cd alias interactively.

That said, I'll quote the path just to make the stupid syntax highlighter happy.

@rkeithhill well.. that's completely inaccurate, but opinions on that aside...

I don't think the syntax highlighting is that bad and one reason you want that in is that GitHub is not the only venue these are viewed. In VS Code you get AMAZING syntax highlighting for these. So if it looks a little iffy on GitHub that's fine.

Yeah, VSCode is where I'm editing this doc. BTW thanks for all your feedback.

Sorry guys! I've been furiously editing the doc as I test the procedure on other systems. I'm "done" for a while. I'll let the requested changes batch up a bit before making any more changes. And yeah, I'll rebase squash this PR as it gets closer to final.

Request for feedback. I'm a bit inconsistent between using the term cross-platform and portable. Cross-platform implies that the binary module loads across OS platforms (to most folks). But that can be satisfied by compiling against netcoreapp2.0. Such a binary will load into PS Core running on any platform supported by PS Core but not Windows PowerShell. I guess portable is somewhat synonymous. What I'm really looking for is that word that says "single binary that runs anywhere including in Windows PowerShell".

After reading through this dotnet standard issue about problems with loading .NET Standard 2.0 libraries in .NET 4.6.1 applications, I think perhaps I should just remove the whole The fix for missing netstandard.dll section. I'm probably just getting lucky and this could all fall apart as different netstandard2.0 binary modules that user varying versions of the same package are imported.

Unless and until, Microsoft provides an update to Windows PowerShell 3 and 5.x that provides all the necessary binding redirects, facades and shims (if this is even possible given that Win PS has to deal with add-ins i.e binary modules), maybe our position should be - this works on .NET 4.7.1 and that's that. IOW your binary module's users will have to be on Windows 10 FCU or higher or they will have to update to .NET 4.7.1. If that isn't acceptable, you'll have to multi-target and build for net461 as well as netstandard2.0. I guess that procedure could be the subject of another "how to".

@joeyaiello or @SteveL-MSFT Can you review?

Are you guys OK with me removing this md file from the markdown.test.ps1 Pester test? I fixed all of the rule errors except for the MD029 errors. Those appear to me to be bogus errors (every list starts with 1 and increments correctly). Either that or perhaps there is a way to suppress this rule?

I think we are using the "One" format. so every item in the list should begin with 1.

1. Do this.
1. Do that.
1. Done.

I think that is actually better long term as it makes it easier to insert items and reorder steps.

@markekraus is right, we are using "One" style. See https://github.com/PowerShell/PowerShell/blob/master/.markdownlint.json

I'm a little perplexed by an "ordered" list where every item is 1.. In that case, what's the point of using an ordered list?

I'd rather change it an unordered list. There is a similar PR for doing this with Visual Studio. It uses an ordered list in the form of 1., 2., 3., etc. How is that documentation getting past this issue? Hint: it has not been added to the markdown.test.ps1 file.

We decided to use the 'One' style because it's easier to add items in the middle of the list in later edits. It will still show as 1,2,3,... after the markdown file is rendered.

Good point on #5096, I will leave a comment there to get that file added to the markdown test.

OK the following ordered list is from https://github.com/PowerShell/PowerShell/blob/master/docs/dev-process/breaking-change-contract.md

So this MD029 rule (set to One) says that list is not right and each item should start with 1., right?

And this list from the Community Governance md is wrong too:

Those 2 markdown files are not captured in markdown.test.ps1, and there are more others too. That test was added after many markdown files were already checked in. Not all .md files were added to the docsToTest list initially because that would be too many files to fix. The idea was to gradually fix all existing .md files. But for new files, we want to make sure they are covered by the test when getting added. /cc @TravisEz13

@rkeithhill Some of the rules are to simplify maintenance (or ensure consistency.) Others are to verify syntax. If we think that any of the consistency rules, make maintenance more complex other than the initial conversion, please open an issue, we can consider disabling the rule. But the spelling check, will silently fail if the syntax is not correct and ignore the entire section where the syntax is not correct. It's important that we start running the syntax checks on all .md files.

@TravisEz13 OK, I think I finally get the MD029 rule. While the procedure appears as step 1, step 1, step 1 in the MD file (which looks kinda borked), it actually shows up as step 1, step 2, step 3 in the rendered view. I was thinking that the rendered view would reflect the step 1, step 1, step 1 - which made no sense to me. :-) I updated the PR so it should pass the markdown pester tests now.

P.S. I'd really like to get someone to review the The fix for missing netstandard.dll section. I'm tempted to pull it out but would like a second opinion.

@rkeithhill Thanks for the update! The ordered style is still used in two other places in command-line-simple-example.md. Can you please update them too?

Just saw that and pushed an update. One beef I have with VSCode is that it doesn't warn you when you commit a file that has unsaved changes. See microsoft/vscode#33004