{"id":20604,"date":"2024-10-30T11:15:36","date_gmt":"2024-10-30T19:15:36","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/powershell\/?p=20604"},"modified":"2024-10-30T16:02:38","modified_gmt":"2024-10-31T00:02:38","slug":"announcing-platyps-100-preview1","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/announcing-platyps-100-preview1\/","title":{"rendered":"Announcing Microsoft.PowerShell.PlatyPS 1.0.0-Preview1"},"content":{"rendered":"<p><!-- markdownlint-disable MD041 --><\/p>\n<p><strong>PlatyPS<\/strong> is the primary tool for creating the PowerShell help displayed using <code>Get-Help<\/code>.\nPowerShell help files are stored in an XML format known as\n<a href=\"https:\/\/wikipedia.org\/wiki\/Microsoft_Assistance_Markup_Language\">Microsoft Assistance Markup Language<\/a> (MAML). Prior to <strong>PlatyPS<\/strong>, the help files were hand\nauthored using complex tool chains. <a href=\"https:\/\/wikipedia.org\/wiki\/Markdown\">Markdown<\/a> is widely used in the open source community,\nsupported by many editors including <a href=\"https:\/\/code.visualstudio.com\">Visual Studio Code<\/a>, and easier to author. <strong>PlatyPS<\/strong>\nsimplifies the process by allowing you to write the help files in Markdown and then converted to\nMAML.<\/p>\n<h2>Announcing Microsoft.PowerShell.PlatyPS<\/h2>\n<p>We&#8217;re pleased to announce the release of <a href=\"https:\/\/www.powershellgallery.com\/packages\/Microsoft.PowerShell.PlatyPS\">Microsoft.PowerShell.PlatyPS 1.0.0-Preview1<\/a>. With\nthis release, there are two versions of PlatyPS.<\/p>\n<ul>\n<li><strong>platyPS v0.14.2<\/strong> is the current version of PlatyPS that&#8217;s used to create PowerShell help files\nin Markdown format.<\/li>\n<li><strong>Microsoft.PowerShell.PlatyPS<\/strong> is the new version of PlatyPS that includes several improvements:\n<ul>\n<li>Provides a more accurate  description of a PowerShell cmdlet and its parameters<\/li>\n<li>Increased performance &#8211; processes 1000s of Markdown files in seconds<\/li>\n<li>Creates an object model of the help file that you can manipulate in memory<\/li>\n<li>Provides cmdlets that you can chain together to perform complex operations<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p>Our main goal for this release is to address long standing issues, add more schema driven\nfeatures, and improve validity checking along with performance. This release is a substantial\nrewrite with all new cmdlets. If you have scripts that use the older version of PlatyPS, you must\nrewrite them to use the new cmdlets.<\/p>\n<p>In this Preview release, we focused on:<\/p>\n<ul>\n<li>Re-write in C# leveraging <a href=\"https:\/\/github.com\/xoofx\/markdig\">markdig<\/a> for parsing Markdown.<\/li>\n<li>New Markdown schema that includes all elements needed for <code>Get-Help<\/code>, plus information that was\npreviously unavailable.<\/li>\n<li>The new cmdlets produce objects, supporting chaining cmdlets for complex operations.<\/li>\n<li>Full serialization to YAML to support our publishing pipeline.<\/li>\n<li>Automatic conversion of existing Markdown to the new object model.<\/li>\n<li>Export of the object model to Markdown, Yaml, and MAML.<\/li>\n<li>The module contains the following cmdlets:\n<ul>\n<li><code>Compare-CommandHelp<\/code><\/li>\n<li><code>Export-MamlCommandHelp<\/code><\/li>\n<li><code>Export-MarkdownCommandHelp<\/code><\/li>\n<li><code>Export-MarkdownModuleFile<\/code><\/li>\n<li><code>Export-YamlCommandHelp<\/code><\/li>\n<li><code>Export-YamlModuleFile<\/code><\/li>\n<li><code>Import-MamlHelp<\/code><\/li>\n<li><code>Import-MarkdownCommandHelp<\/code><\/li>\n<li><code>Import-MarkdownModuleFile<\/code><\/li>\n<li><code>Import-YamlCommandHelp<\/code><\/li>\n<li><code>Import-YamlModuleFile<\/code><\/li>\n<li><code>New-CommandHelp<\/code><\/li>\n<li><code>New-MarkdownCommandHelp<\/code><\/li>\n<li><code>New-UpdateableHelp<\/code><\/li>\n<li><code>Test-MarkdownCommandHelp<\/code><\/li>\n<li><code>Update-CommandHelp<\/code><\/li>\n<li><code>Update-MarkdownCommandHelp<\/code><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p><strong>Microsoft.PowerShell.PlatyPS<\/strong> runs on:<\/p>\n<ul>\n<li>Windows PowerShell 5.1+<\/li>\n<li>PowerShell 7+ on Windows, Linux, and macOS<\/li>\n<\/ul>\n<h2>Installing Microsoft.PowerShell.PlatyPS<\/h2>\n<p>To begin working with <strong>Microsoft.PowerShell.PlatyPS 1.0.0 Preview1<\/strong>, download and install the\nmodule from PSGallery.<\/p>\n<pre><code class=\"language-powershell\">Install-PSResource -Name Microsoft.PowerShell.PlatyPS -Prerelease<\/code><\/pre>\n<h2>Documentation to get started<\/h2>\n<p>For the preview1 release, the cmdlet reference is available at <a href=\"https:\/\/learn.microsoft.com\/powershell\/module\/microsoft.powershell.platyps\">Microsoft.PowerShell.PlatyPS<\/a>.\nFor an example of how to use the new cmdlets, see <em>Example #1<\/em> in <a href=\"https:\/\/learn.microsoft.com\/powershell\/module\/microsoft.powershell.platyps\/new-markdowncommandhelp#example-1-create-markdown-help-files-for-a-module\">New-MarkdownCommandHelp<\/a>.<\/p>\n<h2>Call to action<\/h2>\n<p>Our goal is to make it easier for you to update and maintain PowerShell help files. We value your\nfeedback. Stop by our <a href=\"https:\/\/github.com\/PowerShell\/platyPS\">GitHub repository<\/a> and let us know of any issues you find.<\/p>\n<p>Jason Helmick<\/p>\n<p>Sr. Product Manager, PowerShell<\/p>\n<p><!-- link references --><\/p>\n","protected":false},"excerpt":{"rendered":"<p>We are pleased to announce the release of Microsoft.PowerShell.PlatyPS 1.0.0-Preview1, a tool to build PowerShell help files.<\/p>\n","protected":false},"author":7527,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[3172],"class_list":["post-20604","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-powershell-platyps"],"acf":[],"blog_post_summary":"<p>We are pleased to announce the release of Microsoft.PowerShell.PlatyPS 1.0.0-Preview1, a tool to build PowerShell help files.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/20604","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/7527"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=20604"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/20604\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=20604"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=20604"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=20604"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}