PowerShell Syntax Highlighting with SquareSpace

SquareSpace has been my blogging platform of choice since 2011. My biggest complaint with the platform has always been syntax highlighting. SquareSpace comes with some simple highlighting, but it only supports a few languages, certainly not PowerShell. Over the years I've tried everything from simply using bold and italic text, to using custom HTML and even embedded Pastebin and GitHub Gists. No matter what I tried, I was never happy with the result.

I'd looked and failed to find something that worked. While I was preparing for my post Managing Windows Speculation Control Protections with PowerShell DSC, I decided to take one more look. Stephen Gurnett had written a post about highlighting support for Swift with SquareSpace using Highlight.js. I took a quick look and realised this would work for PowerShell.

Highlight.js provides syntax highlighting for 176 languages with 79 different styles. It features automatic language detection, supports multiple languages per page and works with any markup or js framework. The best part is it's dead simple, even on a SaaS blog like SquareSpace. You don’t need to host the code anywhere as it's available via CloudFlare's CDN.

Getting Started with Highlight.js

The first step is including the code on our site. From the SquareSpace configuration/management screen, navigate to Settings > Advanced (Under Website) > Code Injection. You'll see 4 sections, Header, Footer, Lock Page and Order Confirmation Page. In the header section, add this HTML:

<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/vs2015.min.css">
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/languages/powershell.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

What does this all mean?

The first line tells a visitor’s browser to load another CSS stylesheet. In this example, the Visual Studio 2015 theme. Don’t worry, your existing styles can safely live together with the Highlight.js stylesheet.

The next line loads the Highlight.js JavaScript. This is the code that will make syntax highlighting work on your blog. We're loading it from CloudFlare’s JavaScript CDN.

The third line is important. By default, the Highlight.js that's available from CDN only supports a set of common languages: CSS, JavaScript, C#, Bash, INI, SQL, Markdown, JSON, HTML, etc. Sadly, PowerShell isn’t one of the common languages. To support PowerShell, we need this line to load the support for it.

The last line causes the magic to happen. This line triggers the Highlight.js to go and highlight any code blocks that it finds.

Using Highlight.js

For Highlight.js to work on SquareSpace, you'll need to use the markdown content block and then use the code block syntax. Your Markdown block would look something like:

```
Write-Host 'This is some PowerShell!'
```

That block would result in the this:

Write-Host 'This is some PowerShell!'

Highlight.js will attempt to detect what language is used within the content block, though you can specify the language. I opt to specify the language. You can specify blocks like this:

```json
[
  {
    "title": "apples",
    "count": [12000, 20000],
    "description": {"text": "...", "sensitive": false}
  },
  {
    "title": "oranges",
    "count": [17500, null],
    "description": {"text": "...", "sensitive": false}
  }
]
```

Which results in:

[
  {
    "title": "apples",
    "count": [12000, 20000],
    "description": {"text": "...", "sensitive": false}
  },
  {
    "title": "oranges",
    "count": [17500, null],
    "description": {"text": "...", "sensitive": false}
  }
]

If you don’t want to use markdown for all your content, you can always mix text and markdown blocks.

Issues

So Highlight.js isn’t perfect, especially its PowerShell support. Highlight.js doesn’t properly highlight all PowerShell syntax, for instance, it will only highlight CMDLets that it knows about. Support for things like DSC or Pester isn’t present. While annoying, these aren't show stopping issues.

Conclusion

I hope this helps you work with PowerShell in SquareSpace. Happy Blogging!