Generic way to customize generated markdown about platyps HOT 15 CLOSED

Looking at this one.

from platyps.

Cool, I also though about it recently.
Here is one option: we can

1. switch to markdig (#112) because it has a stable API and is generally very good and extensible parser (this is in turns would be semi-dependent on #205 , but not really, just simpler if do in this order)
2. customization would be super simple and generic:

• callback at the beginning (== start), this is just to initialize things
• callback with passing a path to the file after writing out the whole file on disk (== process)
• callback at the end (== end)

We can even wrap it into a powershell function, because it maps very naturally.
Every callback could overwrite the generated file and leverage markdig for that.
One of motivation examples: resolve links, should be pretty straightforward to implement with this API. Same is probably true for the powershell monikers in the examples.

@BernieWhite do you see any flows?

from platyps.

@vors I think the key flow that will make a difference is before markdown render. Doing some prototyping on a few of the issues raised, they can generally be solved by a simple transformation on the MamlCommand before it is rendered.

Like you say it is probably best to link in markdig first. So I'll look at that approach.

Agreed that would have been easier to have the cross platform upgrade done first :) might take a few commits till we are happy with it.

from platyps.

We should also look at minimizing surface area. To make it easier to plug in a different markdown parser in the future and to make upgrades to the markdig package in the future.

from platyps.

Right, the callback on MamlCommand is also a good extensibility point.

I don't think that it would help with "cross-link relative links", but will definitely help with fixing monikers in examples.

from platyps.

@vors Ok for cross references. My thoughts are that we should leverage link references using convention to identify cross-references. This will make it easy to keep them up to date and they still work as links in GitHub and VSCode (and probably other markdown renderers).

i.e.

[New-MarkdownHelp][xref:New-MarkdownHelp]

[xref:New-MarkdownHelp]: New-MarkdownHelp.md

Not totally sold on the xref identifier only because it potentially clashes with docfx if we don't also use a uid in the header. Other alternatives could be ps or cmdlet.

Also I also had a thought that we could either relative link or link to the uri of the online version.

Thoughts?

from platyps.

oh interesting feature. Is it described in http://spec.commonmark.org/ ?

from platyps.

Link references are defined in the CommonMark spec. Use of : in the link label is permitted in CommonMark.

CommonMark, suggest ways to link markdown documents using full or relative links (when the location of the linked document is known).

CommonMark doesn't define a way to link entities like cmdlets, which is what the cross-references in docfx are trying to achieve. In the case of docfx the location of the linked document is not known at the time of authoring. docfx then does the linking at build time, but for all purposes the markdown documents have links that can't be resolved in the repo.

For the case of platyPS we want CommonMark renderers in editing tools and repos to be able to render the links. PowerShell already does that by topic name.

So my suggestion is just an extension of this, to provide a reference link that can be identified as linking to a cmdlet (as opposed to linking to other content) and updated in a Update-MarkdownHelp pass.

Another suggestion which is a simpler editing experience is to use a shortcut reference link, but it may be harder to identify links that can be automatically updated.

e.g.

[New-MarkdownHelp]

[New-MarkdownHelp]: New-MarkdownHelp.md

from platyps.

#138

from platyps.

Possibly setting an order of precedence is enough and i'm over thinking it.

i.e. If the contents of [] matches a cmdlet with the same name in the same module then link to it and keep the link updated.

from platyps.

updated in a Update-MarkdownHelp pass.

Not following, can you provide an example when it needs an update during this pass? Do you mean updating the LINKS section, if new xref is present?

I like the idea of leveraging the link labels, but want to make sure we know the scenarios we are trying to make better with added complexity.

from platyps.

@vors Yes. Add someone authoring the documentation start linking in parameter descriptions or notes references to cmdlets, we should link them in the related links section.

Also would we ever need to handle a situation where the relative path changed, like the file was renamed or moved to a subdirectory?

The more I think about it, I like the shortcut links better.

from platyps.

The renaming currently is handled pretty badly, even before the cross links we need to solve more basic things #106 .

I personally don't see much value in LINKS section in the context of markdown. Markdown has an overlapping feature reference links.

from platyps.

Reference link definitions themselves are not rendered by the CommonMark spec which isn't a problem for generating maml agreed. But online help needs them. So I can't see a way to not have them :) They would just use the reference link format.

# New-MarkdownHelp
...

## RELATED LINKS

[Character Encoding in the .NET Framework][dotnet-encoding]

[Using PowerShell to write a file in UTF-8 without the BOM][ps-utf]

[Update-MarkdownHelp]

[dotnet-encoding]: https://msdn.microsoft.com/en-us/library/ms404377.aspx
[ps-utf]: http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom
[Update-MarkdownHelp]: Update-MarkdownHelp.md

Since Get-Help -Online is supported in the PS engine, I think we need to account for displaying rendered markdown and it should closely match what is displayed on the command line in terms of content.

from platyps.

Our publishing system supports cross-ref links and markdown reference links. The PowerShell team is considering a switch from MAML to markdown for the help system, but that requires many breaking changes to the help system.

from platyps.