In this article, you’ll learn what Markdown is, how to use it, and why it’s an important tool for the PowerShell administrative scripter.

Back in 2004, a blogger named John Gruber wrote a Perl script called Markdown that automated text-to-HTML conversions for web content creators. John released Markdown under a BSD-style open-source license.

The bad news is that, over the past 11 years or so, Markdown has become a bit fragmented because neither Gruber nor any other community member created a single, accepted standard. The good news is that we PowerShell administrative scripters can easily add Markdown syntax to our toolset and make good use of the language on GitHub.

Why you should care about Markdown ^

Markdown is, at base, a markup language (yes, those open-source types love their puns and wordplay). Its chief advantages are the following:

  • Markdown is easy to read even in its native form (especially when compared to other markup languages such as HTML).
  • Markdown allows us to write rich text by using a simple text editor.
  • The Markdown community offers tools to automate the conversion of Markdown to just about any other file format under the sun.

I trust that you’ve seen the writing on the wall that Git and GitHub are becoming mandatory technologies for Windows systems administrators. GitHub is so heavily invested in Markdown on its site that it actually created a Markdown implementation called, appropriately enough, GitHub-Flavored Markdown.

All GitHub repositories include a readme file called README.md whose content displays immediately below the repository as shown below:

GitHub makes extensive use of Markdown

GitHub makes extensive use of Markdown.

Let’s learn the basics of Markdown syntax, and then we’ll turn our attention to GitHub and finally converting to and from Markdown.

Markdown syntax basics ^

If you’ve ever worked in HTML or (heaven forbid) XML, those markup languages have a heavy, intrusive syntax that can be challenging to read in its uninterpreted form. By contrast, Markdown was written to make even the raw text easy to read.

If you plan to use Markdown to any extent, especially in relation to GitHub-based PowerShell code repositories, then I strongly suggest you purchase a license for MarkdownPad. The free version is pretty good, but you need to buy a license to render GitHub-Flavored Markdown.

In fact, why don’t we use a MarkdownPad 2 screenshot to illustrate the language’s basic syntax rules? Take note of the annotations; I’ll explain them right away.

MarkdownPad 2 shows the raw text at left, and the rendered text at right.

  • A: Use # to ###### to denote heading levels 1 to 6.
  • B: Use **** for bold, and ** for italics.
  • C: Use – for unordered lists.
  • D: Use [hyperlink text](hyperlink URL) for links.

“But what about code?” you’re probably wondering. I’m glad you asked! We’ll assume you’re using GitHub-Flavored Markdown because it’s optimized for rendering source code. By the way, after you buy your MarkdownPad license, you’ll need to open the Options dialog box to enable the enhanced Markdown support as shown here:

Enabling GitHub-Flavored Markdown in MarkdownPad 2

Enabling GitHub-Flavored Markdown in MarkdownPad 2

As you can see in the below screenshot, surround your inline code with backticks (`), and simply tab-indent your code snippets.

GitHub-Flavored Markdown makes it simple to format source code.

You can embed entire PowerShell script blocks, which GitHub-Flavored Markdown color-codes and everything for you, by using the ```powershell directive as shown below:

Embedding a code block in GitHub-Flavored Markdown

Using Markdown with GitHub repositories ^

If you haven’t already done so, please perform the following three tasks:

Next, fire up an elevated PowerShell console and clone a GitHub repo that strikes your fancy. In this example, I’ll clone the Pester PowerShell unit testing module repo:

PS C:\Users\Tim> git clone https://github.com/pester/Pester.git

You’ll now have a new folder populated with the contents of the cloud-based repository. Start MarkdownPad, browse to your local repo directory, and open README.md. You’re in business!

As you can see in the following screenshot, the editing workflow is super simple and very word processor–like. The MarkdownPad toolbar even relieves you from having to remember the Markdown syntax rules!

Editing a local Git repository with MarkdownPad

Editing a local Git repository with MarkdownPad

The rest of the workflow is straight out of the Git playbook. You use git status to view your unstaged changes, git add to stage your newly modified .md file, git commit to snapshot the file, and finally git push to upload the file(s) to your GitHub repo if you have read/write privileges there.

Exporting Markdown content ^

You can export your .md Markdown files from MarkdownPad as HTML or PDF as shown below:

Markdown is eminently exportable and importable

Markdown is eminently exportable and importable.

Of course, we can always turn to the open-source community for help with our rich text export and import needs. For instance, Pandoc is a “Swiss Army knife” open-source, universal document converter that fully supports Markdown. Download the Windows Installer .msi to get started. You’ll need to open a fresh elevated PowerShell console to use the pandoc command.

We can run pandoc –-help to see the supported input/output file formats:

pandoc --help

pandoc.exe [OPTIONS] [FILES]

Input formats:  commonmark, docbook, docx, epub, haddock, html, json*, latex, markdown, markdown_github, markdown_mmd, markdown_phpextra, markdown_strict, mediawiki, native, odt, opml, org, rst, t2t, textile, twiki [ *only Pandoc's JSON version of native AST]

Output formats: asciidoc, beamer, commonmark, context, docbook, docx, dokuwiki, dzslides, epub, epub3, fb2, haddock, html, html5, icml, json*, latex, man, markdown, markdown_github, markdown_mmd, markdown_phpextra, markdown_strict, mediawiki, native, odt, opendocument, opml, org, pdf**, plain, revealjs, rst, rtf, s5, slideous, slidy, texinfo, textile [**for pdf output, use latex or beamer and -o FILENAME.pdf]

As a quick example, let’s use Pandoc to convert our Pester README.md file to Microsoft Word .docx format:

pandoc -f markdown -t docx .\README.md -o readme.docx

In the preceding one-liner, -f denotes the file format, -t represents the “to” or “target” format, and -o signifies the output file name.

For further learning ^

I’ll leave you with a number of hand-selected resources that will help you “level up” your Markdown and Git skills.

For starters, here’s some additional information on Markdown proper:

Next, here’s some help regarding GitHub-Flavored Markdown in particular:

0 Comments

Leave a reply

Please enclose code in pre tags

Your email address will not be published. Required fields are marked *

*

© 4sysops 2006 - 2022

CONTACT US

Please ask IT administration questions in the forums. Any other messages are welcome.

Sending

Log in with your credentials

or    

Forgot your details?

Create Account