{"id":17822,"date":"2008-12-24T07:38:36","date_gmt":"2008-12-24T15:38:36","guid":{"rendered":"http:\/\/devblogs.microsoft.com\/powershell\/?p=17822"},"modified":"2019-06-07T07:39:18","modified_gmt":"2019-06-07T15:39:18","slug":"write-commandblogpost","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/write-commandblogpost\/","title":{"rendered":"Write-CommandBlogPost"},"content":{"rendered":"<p><STYLE>\n    .CmdletName { font-size:large } \n    .CmdletSynopsis { font-size:medium } \n    .CmdletDescription { font-size:medium } \n    .CmdletParameters { font-size:medium }\n    th {\n        font-size: medium;\n        font-style: italic\n    }\n    table {\n        border: 1\n    }\n<\/STYLE><\/p>\n<p><P class=PostHeader>On the PowerShell team, we&#8217;re big believers in the Virtuous Cycle. As you learn PowerShell more and more, things should get easier and easier to do. Inline help is a great example of the virtuous cycle, because it allows you to write scripts in such a way that they&#8217;re easy to learn about the same way you learn about most things in PowerShell (with Get-Help).<\/P>\n<P class=PostHeader>The other great source of learning material for PowerShell is the Internet, and our vibrant PowerShell community. Write-CommandBlogPost is designed to give you an extra benefit of writing help for your commands: you can use this function to (almost) automatically blog them out to the rest of the world.<\/P>\n<P class=PostHeader>Write-CommandBlogPost allows you to blog out help for a command and the command&#8217;s definition in a convenient format, so that you can spend more time making good scripts and less time explaining them to the rest of the world. Believe it or not, you&#8217;re actually reading the output of Write-CommandBlogPost right now. If you don&#8217;t like the output of Write-CommandBlogPost, you can always tweak the script to your liking.<\/P>\n<P class=PostHeader>It&#8217;s things like this that make me think PowerShell is really, really, cool language.<\/P>\n<P class=CmdletName>Write-CommandBlogPost<\/P><BR>\n<P class=CmdletSynopsis><B>Synopsis:<\/B><BR>\n<BLOCKQUOTE>Writes a draft of a blog post for a PowerShell function or cmdlet <\/BLOCKQUOTE><BR>\n<P class=CmdletSyntax><B>Syntax:<\/B><BR>\n<BLOCKQUOTE>Write-CommandBlogPost [-excludeSynopsis] [-excludeSyntax] [-excludeDescription] [-excludeExamples] [-excludeNotes] [-excludeParameters] [-excludeFunction] [-includeCss] [-separator [&lt;Object&gt;]] [-header [&lt;Object&gt;]] [-footer [&lt;Object&gt;]] [-Verbose] [-Debug] [-ErrorAction [&lt;ActionPreference&gt;]] [-WarningAction [&lt;ActionPreference&gt;]] [-ErrorVariable [&lt;String&gt;]] [-WarningVariable [&lt;String&gt;]] [-OutVariable [&lt;String&gt;]] [-OutBuffer [&lt;Int32&gt;]] [&lt;CommonParameters&gt;]<BR>Write-CommandBlogPost [-command [&lt;Object&gt;]] [-excludeSynopsis] [-excludeSyntax] [-excludeDescription] [-excludeExamples] [-excludeNotes] [-excludeParameters] [-excludeFunction] [-includeCss] [-separator [&lt;Object&gt;]] [-header [&lt;Object&gt;]] [-footer [&lt;Object&gt;]] [-Verbose] [-Debug] [-ErrorAction [&lt;ActionPreference&gt;]] [-WarningAction [&lt;ActionPreference&gt;]] [-ErrorVariable [&lt;String&gt;]] [-WarningVariable [&lt;String&gt;]] [-OutVariable [&lt;String&gt;]] [-OutBuffer [&lt;Int32&gt;]] [&lt;CommonParameters&gt;] <\/BLOCKQUOTE><BR>\n<P class=CmdletDescription><B>Detailed Description:<\/B><BR>\n<BLOCKQUOTE>Uses the help information for a command to generate a web page containing<BR>the synopsis, description, examples, notes, parameters, and function body<BR>of a command, as well as an optional header and footer. This encourages<BR>individuals and organizations who write scripts to provide good help, and<BR>saves time in evangelizing commands that have help. <\/BLOCKQUOTE><BR>\n<P class=Examples>Examples: \n<BLOCKQUOTE><PRE class=CmdletExample>    &#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8211; EXAMPLE 1 &#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8212;&#8211;<\/p>\n<p># Writes a blog post about Write-CommandBlogPost and outputs it to a file.\n$header = &#8221;\nOn the PowerShell team, we&#8217;re big believers in the Virtuous Cycle.  As you learn PowerShell more and more, things should\nget easier and easier to do.  Inline help is a great example of the virtuous cycle, because it allows you to write scripts\nin such a way that they&#8217;re easy to learn about the same way you learn about most things in PowerShell (with Get-Help).&#8221;,&#8221;\nThe other great source of learning material for PowerShell is the Internet, and our vibrant PowerShell community.\nWrite-CommandBlogPost is designed to give you an extra benefit of writing help for your commands: you can use this function to (almost)\nautomatically blog them out to the rest of the world.&#8221;,&#8221;\nWrite-CommandBlogPost allows you to blog out help for a command and the command&#8217;s definition in a convenient format,\nso that you can spend more time making good scripts and less time explaining them to the rest of the world.\nBelieve it or not, you&#8217;re actually reading the output of Write-CommandBlogPost right now.  If you don&#8217;t like the output of Write-CommandBlogPost,\nyou can always tweak the script to your liking.\n&#8220;,&#8221;\nIt&#8217;s things like this that make me think PowerShell is really, really, cool language.&#8221;        \nWrite-CommandBlogPost Write-CommandBlogPost -includeCss -header $header -footer &#8220;Hope this Helps,&#8221;, &#8220;James Brundage [MSFT]&#8221; &gt; Write-CommandBlogPost.htm\n    <\/PRE><\/BLOCKQUOTE><BR>\n<P class=CmdletParameters>Command Parameters: \n<BLOCKQUOTE>\n<TABLE class=\"\">\n<COLGROUP>\n<COL>\n<COL><\/COLGROUP>\n<TBODY>\n<TR>\n<TH class=\"\">Name<\/TH>\n<TH class=\"\">Description<\/TH><\/TR>\n<TR>\n<TD class=\"\">command<\/TD>\n<TD class=\"\">The command to write a blog post on. This can be either a cmdlet or an advanced function that has provided detailed help<\/TD><\/TR>\n<TR>\n<TD class=\"\">excludeSynopsis<\/TD>\n<TD class=\"\">If -excludeSynopsis is set, the Synopsis will be excluded from the output<\/TD><\/TR>\n<TR>\n<TD class=\"\">excludeSyntax<\/TD>\n<TD class=\"\">If -excludeSyntax is set, the Syntax will be excluded from the output<\/TD><\/TR>\n<TR>\n<TD class=\"\">excludeDescription<\/TD>\n<TD class=\"\">If -excludeDescription is set, the Description will be excluded from the output<\/TD><\/TR>\n<TR>\n<TD class=\"\">excludeExamples<\/TD>\n<TD class=\"\">If -excludeExamples is set, the examples will be excluded from the output<\/TD><\/TR>\n<TR>\n<TD class=\"\">excludeNotes<\/TD>\n<TD class=\"\">If -excludeNotes is set, the notes will be excluded from the output<\/TD><\/TR>\n<TR>\n<TD class=\"\">excludeParameters<\/TD>\n<TD class=\"\">If -excludeParameters is set, the parameters will be excluded from the output<\/TD><\/TR>\n<TR>\n<TD class=\"\">excludeFunction<\/TD>\n<TD class=\"\">If -excludeFunction is set, the function definition will be excluded from the output. This parameter has no effect if Write-CommandBlogPost is used on a compiled Cmdlet<\/TD><\/TR>\n<TR>\n<TD class=\"\">includeCss<\/TD>\n<TD class=\"\">If -includeCss is set, then the outputted HTML will include a style section to help format the webpage<\/TD><\/TR>\n<TR>\n<TD class=\"\">separator<\/TD>\n<TD class=\"\">By changing the separator, you change what separates different sections of the blog post. By default, the separator is a newline.<\/TD><\/TR>\n<TR>\n<TD class=\"\">header<\/TD>\n<TD class=\"\">The header is content that will be displayed before the blog post, such as an introductory paragraph<\/TD><\/TR>\n<TR>\n<TD class=\"\">footer<\/TD>\n<TD class=\"\">The footer is content that will be displayed after the blog post, such as a closing paragraph or signatur e<\/TD><\/TR><\/TBODY><\/TABLE><\/BLOCKQUOTE><BR>\n<P>Here&#8217;s Write-CommandBlogPost: <I>\n<BLOCKQUOTE><PRE class=CmdletDefinition>function Write-CommandBlogPost {<\/p>\n<p>&lt;#\n.Synopsis\n    Writes a draft of a blog post for a PowerShell function or cmdlet\n.Description\n    Uses the help information for a command to generate a web page containing\n    the synopsis, description, examples, notes, parameters, and function body\n    of a command, as well as an optional header and footer.  This encourages\n    individuals and organizations who write scripts to provide good help, and\n    saves time in evangelizing commands that have help.\n.Parameter Command\n    The command to write a blog post on.  This can be either a cmdlet or an \n    advanced function that has provided detailed help\n.Parameter excludeSynopsis\n    If -excludeSynopsis is set, the Synopsis will be excluded from the output\n.Parameter excludeSyntax\n    If -excludeSyntax is set, the Syntax will be excluded from the output\n.Parameter excludeDescription\n    If -excludeDescription is set, the Description will be excluded from the output\n.Parameter excludeExamples\n    If -excludeExamples is set, the examples will be excluded from the output\n.Parameter excludeNotes\n    If -excludeNotes is set, the notes will be excluded from the output\n.Parameter excludeParameters\n    If -excludeParameters is set, the parameters will be excluded from the output\n.Parameter excludeFunction\n    If -excludeFunction is set, the function definition will be excluded from the output.\n    This parameter has no effect if Write-CommandBlogPost is used on a compiled Cmdlet\n.Parameter includeCss\n    If -includeCss is set, then the outputted HTML will include a style section to help format the webpage\n.Parameter separator\n    By changing the separator, you change what separates different sections of the blog post.\n    By default, the separator is a newline.\n.Parameter header\n    The header is content that will be displayed before the blog post, such as an introductory paragraph\n.Parameter footer\n    The footer is content that will be displayed after the blog post, such as a closing paragraph or signature       \n.Example\n    # Writes a blog post about Write-CommandBlogPost and outputs it to a file.\n    $header = &#8221;\n    On the PowerShell team, we&#8217;re big believers in the Virtuous Cycle.  As you learn PowerShell more and more, things should\n    get easier and easier to do.  Inline help is a great example of the virtuous cycle, because it allows you to write scripts\n    in such a way that they&#8217;re easy to learn about the same way you learn about most things in PowerShell (with Get-Help).&#8221;,&#8221;\n    The other great source of learning material for PowerShell is the Internet, and our vibrant PowerShell community.\n    Write-CommandBlogPost is designed to give you an extra benefit of writing help for your commands: you can use this function to (almost)\n    automatically blog them out to the rest of the world.&#8221;,&#8221;\n    Write-CommandBlogPost allows you to blog out help for a command and the command&#8217;s definition in a convenient format,\n    so that you can spend more time making good scripts and less time explaining them to the rest of the world.\n    Believe it or not, you&#8217;re actually reading the output of Write-CommandBlogPost right now.  If you don&#8217;t like the output of Write-CommandBlogPost,\n    you can always tweak the script to your liking.\n    &#8220;,&#8221;\n    It&#8217;s things like this that make me think PowerShell is really, really, cool language.&#8221;        \n    Write-CommandBlogPost Write-CommandBlogPost -includeCss -header $header -footer &#8220;Hope this Helps,&#8221;, &#8220;James Brundage [MSFT]&#8221; &gt; Write-CommandBlogPost.htm\n#&gt;\n    param(\n        [Parameter(ParameterSetName=&#8217;Command&#8217;,\n            ValueFromPipeline=$true,\n            ValueFromRemainingArguments=$true)]\n        $command,\n        [switch]$excludeSynopsis,\n        [switch]$excludeSyntax,\n        [switch]$excludeDescription,\n        [switch]$excludeExamples,\n        [switch]$excludeNotes,\n        [switch]$excludeParameters,\n        [switch]$excludeFunction,        \n        [switch]$includeCss,                \n        $separator = &#8220;&lt;BR \/&gt;&#8221;,\n        $header,\n        $footer        \n    )\nbegin {<\/p>\n<p>        if ($includeCss) {\n            &#8221;\n&lt;style&gt;\n    .CmdletName { font-size:large } \n    .CmdletSynopsis { font-size:medium } \n    .CmdletDescription { font-size:medium } \n    .CmdletParameters { font-size:medium }\n    th {\n        font-size: medium;\n        font-style: italic\n    }\n    table {\n        border: 1\n    }\n&lt;\/style&gt;\n            &#8221;    \n        }   \n    $originalOFS = $ofs\n    $ofs = &#8221; &#8221;\n    $realHeader = &#8220;&#8221;\n    if ($header) {                    \n        $header | Foreach-Object {\n            $realHeader+=&#8221;&lt;p class=&#8217;PostHeader&#8217;&gt;$(($_ | Out-String -Width 10000).Trim())&lt;\/p&gt;&#8221;\n        }\n    }\n    $realHeader    <\/p>\n<p>}\nprocess {<\/p>\n<p>        foreach ($c in $command) {\n            if ($c -isnot [Management.Automation.CommandInfo]) {\n                $realC = Get-Command $c\n            } else {\n                $realC = $c\n            }            \n            $realC | Foreach-Object {\n                $parameterSection = $null\n                $synopsisSection = $null    \n                $syntaxSection = $null\n                $descriptionSection = $null  \n                $definitionSection = $null             \n                $notesSection = $null\n                $exampleSection = $null                                \n                $nameSection = &#8220;&lt;p class=&#8217;CmdletName&#8217;&gt;$($_.Name)&lt;\/p&gt;&#8221;\n                $help = $_ | Get-Help -ErrorAction SilentlyContinue\n                if ($help) {\n                    $parametersDescribed = $help.Parameters.Parameter | Where-Object { $_.Description }\n                    if (-not $excludeParameters -and $parametersDescribed ) {\n                        $parameterTable = $help.Parameters.Parameter | \n                            Select-Object @{\n                                Name=&#8217;Name&#8217;\n                                Expression={$_.Name}\n                            }, @{\n                                Name=&#8217;Description&#8217;\n                                Expression={($_.Description | Out-String).Trim()}\n                            } | \n                            ConvertTo-Html -Fragment                         \n                        $parameterSection = &#8221;\n&lt;p class=&#8217;CmdletParameters&#8217;&gt;\nCommand Parameters:\n&lt;blockquote&gt;\n$parameterTable\n&lt;\/blockquote&gt;\n&lt;\/p&gt;\n                        &#8221;                            \n                    }\n                    if (-not $excludeSynopsis -and $help.Synopsis) {\n                        $synopsisSection = &#8221;\n&lt;p class=&#8217;CmdletSynopsis&#8217;&gt;\n&lt;b&gt;Synopsis:&lt;\/b&gt;&lt;BR \/&gt;\n    &lt;blockquote&gt;\n    $(($help.Synopsis | Out-String -Width 10000).Trim())\n    &lt;\/blockquote&gt;\n&lt;\/p&gt;\n&#8221;    \n                    }\n                    if (-not $excludeSyntax -and $help.Syntax) {\n                        $syntaxSection = &#8221;\n&lt;p class=&#8217;CmdletSyntax&#8217;&gt;&lt;b&gt;Syntax:&lt;\/b&gt;&lt;BR \/&gt;\n&lt;blockquote&gt;\n$([Security.SecurityElement]::Escape(($help.Syntax | Out-String -Width 10000).Trim()).Replace([Environment]::Newline, &#8216;&lt;BR \/&gt;&#8217;))\n&lt;\/blockquote&gt;\n&lt;\/p&gt;&#8221;\n                    }\n                    if (-not $excludeDescription -and $help.Description) {\n                        $descriptionSection = &#8221;\n&lt;p class=&#8217;CmdletDescription&#8217;&gt;&lt;b&gt;Detailed Description:&lt;\/b&gt;&lt;BR \/&gt;\n&lt;blockquote&gt;\n$(($help.Description | Out-String -Width 10000).Trim().Replace([Environment]::Newline, &#8216;&lt;BR \/&gt;&#8217;))\n&lt;\/blockquote&gt;\n&lt;\/p&gt;&#8221;\n                    }                    \n                    if (-not $excludeNotes -and $help.AlertSet){\n                        $notesSection = &#8221;\n&lt;p class=&#8217;CmdletNotes&#8217;&gt;\n&lt;b&gt;Notes:&lt;\/b&gt;&lt;BR \/&gt;\n&lt;blockquote&gt;\n$(($help.AlertSet | Out-String -Width 10000).Trim().Replace([Environment]::Newline, &#8216;&lt;BR \/&gt;&#8217;))\n&lt;\/blockquote&gt;\n&lt;\/p&gt;&#8221;                        \n                    }\n                    if (-not $excludeExamples -and $help.Examples) {\n                        $exampleText = &#8220;&#8221;                        \n                        $help.Examples.Example | \n                            Foreach-Object {\n                            $exampleText+=&#8221;\n    &lt;blockquote&gt;\n    &lt;pre class=&#8217;CmdletExample&#8217;&gt;\n    $(($_ |Out-String -Width 10000).Trim())\n    &lt;\/pre&gt;\n    &lt;\/blockquote&gt;\n&#8221;\n                        }                        \n                        $exampleSection = &#8221;\n&lt;p class=&#8217;Examples&#8217;&gt;\n    Examples:                            <\/p>\n<p>    $exampleText\n&lt;\/p&gt;&#8221;                         \n                    }                                            \n                }\n                if ($_.ScriptBlock -and (-not $excludeFunction)) {\n$definitionSection = &#8221;\n&lt;p&gt;\nHere&#8217;s $($_.Name):\n&lt;i&gt;\n&lt;blockquote&gt;\n    &lt;pre class=&#8217;CmdletDefinition&#8217;&gt;\nfunction $($_.Name) {\n           $($_.ScriptBlock.ToString().Replace(&#8220;&amp;&#8221;, &#8220;&amp;amp;&#8221;).Replace(&#8220;&lt;&#8220;, &#8220;&amp;lt;&#8221;).Replace(&#8220;&gt;&#8221;,&#8221;&amp;gt;&#8221;))\n}\n    &lt;\/pre&gt;\n&lt;\/blockquote&gt;\n&lt;\/i&gt;\n&lt;\/p&gt;&#8221;                        \n                }\n                $oldOfs = $ofs\n                $realFooter = &#8220;&#8221;\n                if ($footer) {                    \n                    $footer | Foreach-Object {\n                        $realfooter+=&#8221;&lt;p class=&#8217;Postfooter&#8217;&gt;$(($_ | Out-String -Width 10000).Trim())&lt;\/p&gt;&#8221;\n                    }\n                }                \n                $ofs = $separator                \n                &#8220;$($nameSection,\n                    $synopsisSection,\n                    $syntaxSection,\n                    $descriptionSection,\n                    $notesSection,\n                    $exampleSection,\n                    $parameterSection,                    \n                    $definitionSection | \n                        Where-Object { $_ })                \n                &#8221;               \n                $ofs =$oldOFS\n            }\n        }<\/p>\n<p>}\nend {<\/p>\n<p>    $realFooter = &#8220;&#8221;\n    if ($footer) {                    \n        $footer | Foreach-Object {\n            $realfooter+=&#8221;&lt;p class=&#8217;Postfooter&#8217;&gt;$(($_ | Out-String -Width 10000).Trim())&lt;\/p&gt;&#8221;\n        }\n    }\n    $realFooter\n    &#8220;&lt;p style=&#8217;font-size:xx-small&#8217;&gt;Automatically generated with &lt;a href=&#8217;http:\/\/blogs.msdn.com\/powershell\/archive\/tags\/Write-CommandBlogPost\/default.aspx&#8217;&gt;Write-CommandBlogPost&lt;\/a&gt;&lt;\/p&gt;&#8221;\n    $ofs = $originalOfs <\/p>\n<p>}<\/p>\n<p>}\n    <\/PRE><\/BLOCKQUOTE><\/I>\n<P class=Postfooter>Hope this Helps,<\/P>\n<P class=Postfooter>James Brundage [MSFT]<\/P>\n<P style=\"FONT-SIZE: xx-small\">Automatically generated with <A href=\"http:\/\/blogs.msdn.com\/powershell\/archive\/tags\/Write-CommandBlogPost\/default.aspx\">Write-CommandBlogPost<\/A><\/P><\/p>\n","protected":false},"excerpt":{"rendered":"<p>On the PowerShell team, we&#8217;re big believers in the Virtuous Cycle. As you learn PowerShell more and more, things should get easier and easier to do. Inline help is a great example of the virtuous cycle, because it allows you to write scripts in such a way that they&#8217;re easy to learn about the same [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-17822","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell"],"acf":[],"blog_post_summary":"<p>On the PowerShell team, we&#8217;re big believers in the Virtuous Cycle. As you learn PowerShell more and more, things should get easier and easier to do. Inline help is a great example of the virtuous cycle, because it allows you to write scripts in such a way that they&#8217;re easy to learn about the same [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/17822","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\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=17822"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/17822\/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=17822"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=17822"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=17822"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}