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!

What am I reading?

Just a quick post about the blogs found in my RSS reader. It is all pretty self explanatory!

Comics

PHD Comics http://www.phdcomics.com
Penny Arcade http://www.penny-arcade.com
xkcd.com http://xkcd.com/
Dilbert http://dilbert.com/

Microsoft (and related) blogs

Security Research & Defense http://blogs.technet.com/b/srd/
Powershell.CA http://www.energizedtech.com/
MSRC http://blogs.technet.com/b/msrc/
Richard Hicks' DirectAccess Blog http://directaccess.richardhicks.com
Microsoft Security Bulletins http://technet.microsoft.com/security/bulletin
Jeff Alexander's Weblog http://blogs.technet.com/b/jeffa36/
istartedsomething http://www.istartedsomething.com
Ben Armstrong http://blogs.msdn.com/b/virtual_pc_guy/
Bink.nu News http://www.bink.nu
WinBeta | Microsoft centered, Technology focused http://www.winbeta.org
Group Policy Central http://grouppolicy.biz

Security

Darknet - The Darkside http://www.darknet.org.uk
F-Secure Antivirus Research Weblog  http://www.f-secure.com/weblog
security.crudtastic.com  http://security.crudtastic.com
Hak5 - Technolust since 2005 http://hak5.org
Schneier on Security  https://www.schneier.com/blog/
Packet Storm Security http://packetstormsecurity.com/

General

IFTTT Blog http://blog.ifttt.com/
Ars Technica http://arstechnica.com
LifeHacker Australia http://lifehacker.com.au
The Food Avenue...Diary of a food addict http://thefoodavenue.com