- Install Ansible on Windows - Thu, Jul 20 2023
- Use Azure Bastion as a jump host for RDP and SSH - Tue, Apr 18 2023
- Azure Virtual Desktop: Getting started - Fri, Apr 14 2023
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.
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
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:
- Install MarkdownPad or another Markdown editor of your choice.
- Install and configure Git for Windows.
- Create a free GitHub user account.
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
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.
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:
