Deploying a quick Markdown Site on Azure
Tags: azure, python, webdev
Published: 2020-02-22 15:11:49

# Deploying Markdown Site on Azure

![Markdown page to site](https://www.dishy.dev/articles/images/mkdown-to-site.PNG)

This blog was originally posted on my [site](https://www.dishy.dev/articles/generating-py-mk/) and I thought I might share it here. I've found a pattern I like using a python markdown generator to get a simple site up and running quickly. I had three main requirements

- Markdown
    - I wanted to use Markdown as I use it day to day, and I think its a quick way to get ideas down without having to mess around with rich text formatting.
- Static Site
    - I wanted to keep this as simple and clean as possible, just HTML, CSS and JS.
- Azure
    - I wanted to deploy the site through Azure as its the cloud service I'm most familiar with.

## MkDocs
[MkDocs](https://www.mkdocs.org/) is a really elegant, fast way to build a static site from markdown. You can create a site from just a configuration file and a set of markdown files. Getting started is as simple as

``` bash
pip install mkdocs
mkdocs new my-new-project
mkdocs serve
```

And viola! You've got a site with navigation, search facility, table of contents and a theme that renders nicely on mobile and desktop.

![MkDocs New Site Landing Page](https://www.dishy.dev/articles/images/mkdocs-home-screen.PNG)

Whenever you save a change to the site it gets rebuilt.

![Gif of applying an update to an MkDoc](https://www.dishy.dev/articles/images/mkdocs-update.gif)

Adding new pages and updating the navigation is just updating the root `mkdocs.yml` YAML file to point towards new markdown files.

``` yaml
site_name: Dishy Dev
nav:
  - Home: index.md
  - Article:
    - 'My Cool Article': 'articles/cool-article-1.md'
```

![Example of the MkDocs Navigation Bar](https://www.dishy.dev/articles/images/mkdocs-nav.PNG)

### Themes
MkDocs comes with a selection of [themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) that can be easily installed through pip. In the end I went with [Cinder](https://sourcefoundry.org/cinder/), a clean style based on Bootstrap.
After `pip install mkdocs-cinder` getting it going was updating the `mkdocs.yml` file.

```
theme: cinder
```

![MkDocs New Site with Cinder Theme applied](https://www.dishy.dev/articles/images/mkdocs-home-screen-cinder.PNG)

### Hosting Static Site
The quickest and easiest way for me to start hosting my site was through an Azure Storage account. Azure Storage supports [Static Site Hosting](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website) where you can serve up the contents of a container called `$web`.

![Dashboard of the Azure Storage Static Sites](https://www.dishy.dev/articles/images/azure-static-site.PNG)

### Building Site

Building the site is done through the `mkdocs build` command. This generates a **sites** directory. MkDocs will give you everything you need for your site, you just need to get those files served up over a web server.

I just used [Azure Storage Explorer](https://azure.microsoft.com/en-us/features/storage-explorer/) to upload the generated site directory into Azure Storage.

![Screenshot of using Azure Storage Explorer to upload files](https://www.dishy.dev/articles/images/azure-storage-explorer.PNG)

In future I'm going to look at how to automate this step so the site can be rebuilt and re-uploaded every time a new version is created (Azure Functions with an Event on the Storage Container possibly).

### Adding a CDN
Something that caused me a lot of fustration and wasted time was trying to link my domain name to my storage. Ideally I wanted to serve up the contents of my storage straight through the `dishy.dev` domain name. I couldn't get the storage serving up over the root domain, it was always on a subdomain.

In the end I found out that the scenario I was trying to do wasn't possible, and that using a CDN to serve up the storage contents would allow me to quickly link my domain.

CDN setup can be quite confusing but Microsoft have some [good guidance](https://docs.microsoft.com/en-us/azure/storage/blobs/static-website-content-delivery-network) on how to do it. Remember to enable [http to https redirection](https://docs.microsoft.com/en-gb/azure/cdn/cdn-storage-custom-domain-https#http-to-https-redirection) in your CDN rules. And if you want to let people access your site without needing "www." at the front [Arlan Blogs - Adding a Root Domain to Azure CDN Endpoint](https://arlanblogs.alvarnet.com/adding-a-root-domain-to-azure-cdn-endpoint/) has instructions on how to do this.

![Screenshot of settings for redirecting http to https in Azure CDN](https://www.dishy.dev/articles/images/azure-cdn-http-to-https.PNG)

### Adding Telemetry
In the `mkdocs.yml` I added a link to an [Azure Application Insights Snippet](https://docs.microsoft.com/en-us/azure/azure-monitor/app/javascript#snippet-based-setup) to let me see what sort of traffic the site was generating.

``` yaml
extra_javascript:
  - 'scripts/application_insights.js'
```

![Azure Application insights page loading statics example](https://www.dishy.dev/articles/images/azure-application-insights-page-load.PNG)

--------

And there you have it, not bad for a couple of hours work. A really quick way to stand up a quick site for blogging or documentation.

MkDocs is very extendable with a lot of [plugins](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins) available to easily expand your site. Tagging of your pages, Minifiers for your build etc so there's plenty of scope to build more complex sites.