Markdown Notes with VS Code

Over the years I have managed my notes in many different ways. I’ve used Notion, OneNote, Evernote, and probably more that I don’t even remember. At the same time I was writing a lot more code, and creating documentation for web applications and APIs. This naturally got me using a whole lot more Markdown.

At this point Markdown truly is ubiquitous and it’s the defacto standard for writing technical documentation. Naturally, the more I used it the more I began to enjoy it. I started to wonder how I could incorporate it into my normal note taking activities. As an engineer, I take a lot of notes - many of them are technical in nature. It felt only natural to start using this in my normal workflow. I finally ended up settling on Visual Studio Code in combination with several plugins. I’ll take you through what I’m using, and also what I tried previously.

Read on to learn more!

Purge Cloudflare Cache with PowerShell & Azure DevOps

Originally when I setup my blog on Static website hosting in Azure Storage I went with Azure CDN because I wanted to have an SSL endpoint. As of right now, you cannot do custom SSL with static website hosting unless you use Azure CDN.

But then I hit another snag, you cannot redirect the root domain and redirects in general were a bit too complex for a simple project like this one. There is a user voice suggestion for this feature but it remains under review. This started to bother me because I wanted to do redirects with SSL but couldn’t because the I could not install the certificate generated by Azure CDN on the Linux VM I decided to do the rewrites on. All my previous articles were on breaking all of my links from places like Google and Bing, or even worse resulting in the dreaded SSL error.

Fast forward a bit to Cloudflare. In a previous life I used their free plan to protect against attack but that free plan also offers 3 free redirects AND a free SSL endpoint. This meant I could now redirect to www. where my CNAME is setup for Azure Storage. It also meant I could redirect a bunch of my other domains like and have all my URLs work how I wanted. Nobody else will probably notice this.. but it’s one of those things I wanted in place - I am weird like that!

But I digress, now that I am on Cloudflare I wanted to make sure that the Cloudflare CDN cache has my latest content whenever I publish. This is probably overkill in some places because Cloudflare seems to pick up on new content fairly quickly. But at least at the end of my release pipeline I’ll know everything is published on the CDN.

This guide assumes a few things are already done.

  • You’ve setup a Cloudflare account and your domain is pointed to their name servers for hosting. You can find instructions in Cloudflare 101.
  • You’ve already setup your CNAME to point to Azure Storage (or other endpoint).
  • You have obtained your API Token for the v4 API
  • You already have a release pipeline setup, see my previous article for more information.

Using Azure DevOps to deploy Hexo

One of the things that I wanted to be able to do was setup a full CI/CD pipeline for my blog. As someone once said If it’s worth doing, it’s worth overdoing and it was in that spirit I configured Azure DevOps to deploy Hexo.


First off a short intro to Azure DevOps. Previously known as Visual Studio Team Services (VSTS) it is a service that allows you to manage code repositories, boards, pipelines (which we’ll cover here) and even test plans. You can also use Azure Pipelines with GitHub and while I did not do that here because I wanted all my repos to be private, there is no reason you cannot use GitHub as your source repo. Especially since two weeks ago they announced free private repos.

This article will cover the following:

  1. Configuring your build in Azure Pipelines
    • Install npm
    • Install hexo-cli
    • Generate the static site
    • Publish the build artifacts
    • Enable continuous integration
  2. Configuring your release in Azure Pipelines
    • Select your source artifacts
    • Enable AzureBlob file copy to copy content to $web
  3. Running your first build!

If you haven’t used Azure DevOps before there is an article covering how to get started.


I will be assuming that a few things are already in place for the purposes of this guide.

  1. You’ll need to get Hexo configured locally and committed to a repo. I covered how to get Hexo running in the Windows Subsystem for Linux in a previous article.
  2. Your site committed to an Azure DevOps or GitHub repository.
  3. An Azure Storage Account provisioned and static website hosting enabled. This process would likely work for other services, but this article will explain how to do it with an azure account.

Using WSL and Node.js to build and manage Hexo

I had initially intended to publish this as part of my Azure DevOps entry, but it felt like it needed its own dedicated article. For my Hexo workflow I decided I wanted to use the Windows Subsystem for Linux from here on referred to as WSL. This works best for me because I am primarily a Windows user and I also have a fair bit of experience with Linux.

Getting Started

The first thing you’ll need to do is get Hexo configured locally so that you can generate the static content for later deployment, and also run your local server to test your content. The basics on how to configure Hexo are available on their website, I’ll cover how to do it on WSL specifically.

The first thing you need to do if you have not already is get WSL installed and running. Step by step instructions on this are available over on Microsoft Docs. The instructions below are specifically for the Ubuntu distro.

The below instructions assume a fresh install of the Ubuntu distro from the Windows store.

Getting npm and Node.js installed

You’ll need git for a variety of reasons, so let’s just get it installed first along with all of the prerequisites.

Install Git

sudo apt-get install git-core

Install NVM & Node.js

This is using Node Version Manager by creationix on GitHub. There are many ways to install Node.js, I went with the Hexo documentation.

Download and run installation script:

wget -qO- | bash

Load NVM if it isn’t already loaded:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/" ] && \. "$NVM_DIR/" # This loads nvm

FInally, install node.js

nvm install stable

Install npm

In this step we’ll install the node package manager. npm is a package manager for node that will then allow you to install Hexo, plugins, and anything else you’d like to do with node.

sudo apt install npm

Install Hexo

At this point we are ready to install the Hexo cli which will allow you to finally build out a hexo environment.

npm install -g hexo-cli

Initialize a new blog

With WSL you can actually navigate to the Windows file system which means you can utilize tools like Visual Studio Code to edit your articles, templates and configuration files. For purposes of this article lets say we want to get Hexo running in c:\hexo

You can actually customize the mount point noted below. For example you could change it to /c/hexo instead of /mnt/c/hexo by modifying wsl.conf. You can also use these steps if you find that your Windows drives are not mounted inside WSL.

root = /
options = "metadata"

Full documentation on settings available in wsl.conf is available here.

Now initialize a new site in that location:

hexo init /mnt/c/hexo
cd /mnt/c/hexo
npm install

You will then have the following folder structure:

├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

That’s it! Now you are ready to configure your blog and start authoring content. Documentation for editing your site configuration can be found here.

Finishing Up

Now that you have the basics in place you can commit the directory to GitHub or Azure Devops and begin authoring posts and even installing custom themes if you want. Below are a few links to get you started:

  • Writing Content - This explains how to write new posts and pages as well as create drafts.
  • Miscellaneous Commands - This contains documentation on how to generate a static site, or launch a local server to test your newly created content.

I hope this article was helpful! You are now well on your way to publishing a Hexo blog in the wild. In my next article I will cover how to automatically deploy Hexo using an Azure Pipeline.

Why I chose Hexo for my Technical Blog

When the time came to relaunch my blog I spent a fair amount of time researching options. I wanted something that worked well for me that didn’t require too much infrastructure. I also wanted to keep costs fairly low and not take on a large monthly recurring cost.

  • Ideally, I wanted static content that I could host in an Azure Storage account or some sort of static website hosting.
  • I wanted something that felt comfortable for me. I spend a fair amount of time authoring articles in Markdown and it has really grown on me over the past few years.
  • An application with a fair amount of plugin and theme options, I don’t really want to get involved in creating a custom template. A reasonably sized community was a plus.

The Competitors

I evaluated a variety of different options before settling on Hexo. Obviously I’m sure there are more options out there, but this is what I looked at.

  • DocFX - I’ve had some experience with DocFX in the past and honestly, it is what I really wanted to use. But the lack of theme selection and the fact it’s primarily focused on documentation meant it was not a great fit for what I wanted to do. It is the engine behind Microsoft Docs and it does that really well so I will continue to monitor the project.
  • Hugo - A close second, Hugo is very similar to Hexo. It is built on Go rather than Node.js. It generates a static site that you can publish in much the same way. The configuration seemed a little bit more involved, but in the end it was almost a coin flip. Now that my content is in Markdown and ready to roll I may still give Hugo a try to compare and contrast.
  • Ghost - Their hosted platform pricing was a bit steep for me. And while they did offer self hosting the config seemed fairly complex and the requirements were also steep. I also don’t really need the fancy admin interface.
  • Medium - This is where my blog was before. It is a great platform for getting your content out there. But it’s not really a great platform for the true technical blogging that I wanted to do. I do still intend to post opinion pieces.. but not enough that Mediums core benefit would be that useful.
  • Wordpress - Obviously this option is one of the largest out there. And there are definitely a ton of options for plugins and themes. And I have experience with it in the past. But for me it felt like using a bulldozer to solve something I could use a shovel for.

Hyper-V Best Practices

When deploying Windows Server as a hypervisor host for virtual machine workloads there are a variety of best practices that should be put in place. Running Hyper-V on Windows has special considerations when it comes to workload. For example, Virtual Machine Queues and Hyper-V Specific hotfixes. This is blog entry serves as an overview of important checks you should ensure are in place.

General Host Considerations

Starting with your base operating system you should strongly consider Windows Server Core. Server Core has a much lower attack surface as well as lower resource utilization and reduced patching requirements. This is important when running a VM workload as it frees up additional resources for your virtual machines. And the reduced patching allows for greater availability of tenant workloads.

Additionally, consider running minimal roles and features on your host operating system. IIS for example should never be installed on a host as it uses valuable resources and also increases your attack surface. If your host will be clustered, obviously, Failover Cluster Manager and Multipath I/O will need to be installed to access shared storage. Any Anti-Virus installed on the host should be configured to ignore Hyper-V specific files like VHDs, aVHDs, VHDx and VSV.

Drivers and Firmware

Ensure that all of the latest drivers and firmware for your hardware are installed on the host operating system. This is critical because inbox drivers included with Windows are not intended for long term use. Many of the features that Hyper-V takes advantage of on the networking layer require the latest and greatest network card drivers. We have seen outdated drivers and firmware cause reduced performance and instability Hyper-V hosts. Hyper-V adds a layer of complexity which is often times more sensitive to driver and firmware versions.

If you’re clustering Hyper-V, put in place a process to be sure that every single one of your nodes is running the same driver revisions and software updates.

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now