Add support for Alias information to cmdlet schema

[sdwheeler]

Summary of the new feature / enhancement

As a user I need an easy way to search for cmdlet reference by the cmdlet alias.

Most cmdlet reference docs do not contain information about cmdlet aliases. If they do mention the alias, there is no standard pattern for documenting the alias. The docs platform does not have a way to search for cmdlets by alias.

Goals

1. Provide alias information in a way that the docs platform can use it to enhance search
2. Standardize how cmdlet aliases are documented making the information easier to find by readers and search engines
3. New-MarkdownHelp should create the empty template information for an author to populate

Proposed technical implementation details (optional)

Add YAML metadata frontmatter to list aliases by platform. For example:

alias:
  - all: dir, gci
  - windows: ls
  - macos:
  - linux:

Add a new H2 section after SYNOPSIS and before SYNTAX for documenting the aliases. For example:

## ALIASES

This cmdlet supports the following aliases on the following platforms:

- All platforms: `dir`, `gci`
- Windows: `ls`

See alias-prototype.md for a more complete example.

[theJasonHelmick]

@sdwheeler - Thank you for adding this issue -- I'll get into the spec.

[JamesWTruher]

@sdwheeler, @theJasonHelmick
would this be something that is applied automatically? The alias attribute does not support a specific alias for a specific platform (it's just a collection of strings)? FWIW, the number of cmdlets that have a cmdlet alias specified in custom attributes (in current pwsh) is quite small, only 5 out of 1000s

[sdwheeler]

The request here is to support the metadata. It is up to the author to populate the information. This information will be used by the publishing platform.

[JamesWTruher]

@sdwheeler @theJasonHelmick

is there a reason why the yaml should not look like this:

alias:
  - windows: ls, dir
  - macos: dir
  - linux: dir

The reason is that you likely have the same aliases for macos and linux nearly all the time:

alias:
  - windows: dir
  - macos: ls
  - linux: ls

It seems like do too much to have an all - alternatively, you may want to take this approach:

alias:
  - dir: windows, macos, linux
  - ls: macos, linux

Then you might be able to argue that all could work:

alias:
  - dir: all
  - ls: macos, linux

The object model does not need to look exactly like the markdown (in some cases, that may not be a good idea)

[theJasonHelmick]

This is included in the Microsoft.PowerShell.PlatyPS 1.0 release.

[sdwheeler]

Reopening. This hasn't been completed yet.

There are two parts to documenting aliases.

• Part 1 - We need a list of aliases as data that the build pipeline can consume so that it can decorate the TOC with aliases.
  • This list should contain all aliases for the command on all platforms.
  • The list does not need to know which aliases are available on which platforms.
  • The list will be hand authored
  • The list will be in the Yaml frontmatter of the markdown file
• Part 2 - We need an H2 for ALIASES with arbitrary markdown that describes the aliases.
  • The description will be hand authored.
  • It is up to the author to ensure that the list in the metadata is properly reflected in the markdown description under the H2.
  • PlatyPS will do no validation of the information.

Questions:

• How should the frontmatter metadata be written? Suggest using a Yaml array of strings similar to the no-loc key that we already use.

  Example:

  aliases: [ dir, gci, ls ]

@JamesWTruher Comments? Suggestions?

[sdwheeler]

It appears that 27d5ffe now supports this format:

aliases: [ dir, gci, ls ]