diff --git a/platyPS.schema.md b/platyPS.schema.md index 25b8d7f5..67fdd38d 100644 --- a/platyPS.schema.md +++ b/platyPS.schema.md @@ -11,7 +11,7 @@ It closely resembles output of `Get-Help`. * tabs show the scopes of `// for` statements; they should not be included in the Markdown output. ### Version 2.0.0 - + // Every cmdlet help placed in it's own `Command-Name.md` file in one folder. // We sometimes reference to this folder as "HelpModule". @@ -32,36 +32,41 @@ It closely resembles output of `Get-Help`. // following level-2 headers sections can go in any order // here is the recommended order - + ## SYNOPSIS + {{Synopsis text}} ## SYNTAX + // for each parameter set ### {Parameter Set Name, if default parameter set, followed by "(Default)"} + // i.e.: FromPath (Default) // This syntax would be ignored during maml generation. // syntax would be generated from parameters metadata - ``` + ```{Syntax language, i.e. PowerShell or nothing for plain text} {{Output of Get-Command -Syntax}} ``` ## DESCRIPTION + {{Description text}} ## EXAMPLES + // for every example ### {Example Name} {{Example introduction text}} - + // one or more times, codesnippet // it's useful to put the ```powershell code // before the plain text command exectution output ```{Syntax language, i.e. PowerShell or nothing for plain text} {{Example body}} ``` - + {{Example remarks}} // not a mandatory, i.e. TechNet articles don't use remarks ## PARAMETERS @@ -69,10 +74,11 @@ It closely resembles output of `Get-Help`. // for every parameter // default value is non-mandatory ### -{Parameter name} + {{Parameter description text. It can also include codesnippets, but they could not be ```yaml}} // parameter metadata - // for every unique parameter metadata set + // for every unique parameter metadata set // Note: two Parameter Sets can have the same parameter as mandatory and non-mandatory // then we put them in two yaml snippets. // If they have the same metadata, we put them in one yaml snippet. @@ -83,29 +89,36 @@ It closely resembles output of `Get-Help`. Accepted values: {ValidateSet, comma-separated list of valid values, i.e. Foo, Bar} // if ommitted => everything is accepted Applicable: {comma-separated list of tags where this cmdlet exists} // if omitted then applicable for any tag // break line to improve readability and separate metadata block - + Required: {true | false} Position: {1..n} | named Default value: {None | False (for switch parameters) | the actual default value} Accept pipeline input: {false | true (ByValue, ByPropertyName)} Accept wildcard characters: {true | false} ``` + // if supports workflow parameters ### + {{ Workflow common parameters text, would be ingored during maml generation }} // if supports common parameters ### + {{ Common parameters text, would be ingored during maml generation }} ## INPUTS + // for every input type ### {Input type} + {{Description text}} ## OUTPUTS + // for every output type ### {Output type} + {{Description text}} ## RELATED LINKS @@ -114,18 +127,21 @@ It closely resembles output of `Get-Help`. [{link name}]({link url}) ### Version 1.0.0 (Deprecated) + v0.7.6 is the last platyPS version that supports it. // for every command: # {Command name} - + // following level-2 headers sections can go in any order // here is the recommended order - + ## SYNOPSIS + {{Synopsis text}} ## DESCRIPTION + {{Description text}} ## PARAMETERS @@ -144,16 +160,21 @@ v0.7.6 is the last platyPS version that supports it. {{Parameter description text}} ## INPUTS + // for every input type ### {Input type} + {{Description text}} ## OUTPUTS + // for every output type + ### {Output type} {{Description text}} ## EXAMPLES + // for every example ### {Example Name} diff --git a/templates/aboutTemplate.md b/templates/aboutTemplate.md index d6ea723f..0e2951dc 100644 --- a/templates/aboutTemplate.md +++ b/templates/aboutTemplate.md @@ -1,4 +1,5 @@ # {{TOPIC NAME}} + ## {{FileNameForHelpSystem}} ``` @@ -17,6 +18,7 @@ The second header should have no spaces. ``` # SHORT DESCRIPTION + {{ Short Description Placeholder }} ``` @@ -27,28 +29,35 @@ The generated about topic will be encoded UTF-8. ``` # LONG DESCRIPTION + {{ Long Description Placeholder }} ## Optional Subtopics + {{ Optional Subtopic Placeholder }} # EXAMPLES + {{ Code or descriptive examples of how to leverage the functions described. }} # NOTE + {{ Note Placeholder - Additional information that a user needs to know.}} # TROUBLESHOOTING NOTE + {{ Troubleshooting Placeholder - Warns users of bugs}} {{ Explains behavior that is likely to change with fixes }} # SEE ALSO + {{ See also placeholder }} {{ You can also list related articles, blogs, and video URLs. }} # KEYWORDS + {{List alternate names or titles for this topic that readers might use.}} - {{ Keyword Placeholder }}