3

#PSTip GitHub PowerShell syntax highlighting in Markdown

GitHub, a service for hosting development projects that can be written in many programing and scripting languages has its own extensions to the popular Markdown style. This allows us to add syntax highlighting in our Markdown files inside of our repositories (like the README.md file). Also, when opening  Issues, Pull Request and even on the  Wiki we can use it in code blocks to syntax highlight code following one of the supported language types.

The way we specify what type of syntax highlighting should be used for processing the code block is by adding at the front of the triple backtick marker used by Github the name of the language. In the case of PowerShell it would be:

<code></code><code>PowerShell

</code><code></code>

Here is an example of an advanced function template:

<code></code><code>PowerShell
&lt;#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
#&gt;
function Verb-Noun
{
    [CmdletBinding()]

    [OutputType([int])]

    Param
    (
        # Param1 help description
        [Parameter(Mandatory=$true,
                   ValueFromPipelineByPropertyName=$true,
                   Position=0)]
        $Param1,

        # Param2 help description
        [int]
        $Param2
    )

    Begin
    {
    }

    Process
    {
    }

    End
    {
    }
}
</code><code></code>

GitHub would render this in the following manner:

GitExample

If you plan to use Markdown files in your project to document it or to generate documentation you will later export to HTML or PDF, you can also use a program called MarkdownPad 2 Pro . The Pro version allows use of the GitHub Markdown Engine in its Options.

image003

This works great when one wants to edit the Markdown files locally and see a preview of how they would look rendered.

image004

Filed in: Columns, Tips and Tricks Tags: , ,

3 Responses to "#PSTip GitHub PowerShell syntax highlighting in Markdown"

  1. sstranger says:

    Hi Carlos,
    Maybe you can explain why I should create Markdown files when publishing on Github or somewhere else?
    What are the benefits?
    I’m new to this, so it could be just a lack of knowledge on my side

  2. Ravikanth says:

    I use MarkdownPad Pro and it makes life so easy. I love the simplicity and the clean layout that this software produces.

Leave a Reply

Submit Comment

© 2016 PowerShell Magazine. All rights reserved. XHTML / CSS Valid.
Proudly designed by Theme Junkie.
%d bloggers like this: