Publish a Static Website in a Day with MkDocs and Netlify

Intro

I recently got around to publishing my personal website and the whole experience was so delightful I felt it important to share my process. It took me about 8 working hours (including research and reading docs). For some scale, this blog post will have taken me about 2X that amount of time 😱.

As we go through this tutorial, feel free to use my website and the source code as a practical example.

Background

I’ve been telling myself for a while now that I was going to set up a personal website. My requirements were:

1. Clean, accessible design.
2. Mobile-friendly.
3. Easy to update.
4. Simple to deploy.

This is all complicated by the fact that I have almost zero experience with any modern front-end framework, having largely focused on back-end web-services and data engineering for the vast majority of my career up until this point. While there are plenty of tutorials out there for publishing simple websites with React/Vue/etc., I was hesitant to invest in these technologies, knowing that I rarely spend my time using them, let alone using JavaScript, in my day-to-day work. This meant that while these frameworks may check most of the boxes, they failed to check off 3 (easy to update) for me.

However, I recently came across two components that together seemed to check off all the boxes: MkDocs and Netlify. MkDocs is a Python library for generating beautiful, configurable static sites written in Markdown and Netlify is a service for automatically publishing websites directly from the VCS service of your choice with a very good free offering.

I was eager to make use of these two technologies together and when I looked over my four requirements for my own website, I realized I had the perfect excuse.

Pre-Reqs

This post assumes some familiarity with Python, Poetry, and Markdown. Don’t worry, you don’t need to be a pro at any of these — just make sure you’ve got Python 3 installed and Poetry set up.

Create the Source

Set Up Your Environment

First thing’s first, we need to get our development environment set up. First, create a directory, we’ll call it website, and run poetry init. Poetry will now take you through generating a pyproject.toml for your website. This is a newer standard for describing a python project, as defined in PEP 518.

Create your project directory and initialize with poetry

Note in the animation above I’ve defined the following dependencies:

1. mkdocs: The static site generator — required for this tutorial.
2. mkdocs-material: An optional mkdocs extension which generates your site using Material Design. I chose this for my website because it checks off requirements (1) and (2). You can see an official list of third-party themes in the MkDocs Wiki.
3. pymdown-extensions: An optional markdown plugin which adds a whole host of useful markdown extensions which we’ll configure later in this tutorial.
4. fontawesome-markdown: An optional markdown plugin which adds native support for font-awesome glyphs directly within your markdown using the same syntax as emojis.

Once you’ve defined your dependencies, just run poetry install:

Create a new virtualenv and install the dependencies

Pro-tip: Poetry will store your virtualenv in a global cache directory, but I prefer to have my virtualenv created in my project directory. You can turn this on by running poetry config virtualenv.in-project true before running poetry install.

Initialize MkDocs

MkDocs is a fantastic tool for creating documentation and static websites from markdown. While there are some trade-offs vs. Sphinx/rST (such as limited autodoc support), I think MkDocs really shines in a few major areas:

1. Your docs are written in Markdown, which is a gold-standard, cross-platform text markup with fantastic support.
2. MkDocs comes packaged with a built-in development server with live reloading. This is a huge improvement over the docs-writing life-cycle with Sphinx.
3. Simple, transparent configuration with mkdocs.yml.

Initializing a mkdocs-based website is extraordinarily simple:

Initialize the mkdocs project scaffolding and turn on the server

Customize and Configure Your Site

Now that we’ve got a basic site set up, we can get to the fun part — actually putting together a website! In this case, there’s very little you need to do.

Read the Docs

It may seem odd that I’m pointing you elsewhere for answers, but the MkDocs Homepage has a great tutorial which will get you started understanding the fundamentals, so I recommend you give it a look before proceeding.

Additionally, if you’re using MkDocs-Material, I recommend giving their docs a read as well.

Add Some Extras

Remember those extra dependencies I listed? Now that you’re familiar with the mkdocs.yml file, it’s time to add in the extras. Here’s an example from my own website’s configuration:

Pro-Tip: Any extension to Python’s Markdown library is a valid extension for MkDocs. This is why we can take advantage of the Font Awesome Markdown library we installed by just listing it in the markdown_extensions block.

Deploy Your Site on Netlify

Netlify is a fantastic hosting solution that is remarkably easy to set up and a very good free tier. They also provide a DNS service and TLS for your custom domains, meaning your website will be secure from the get-go. All that’s needed to get your website set up to use Netlify is a couple of files:

1. runtime.txt containing your Python version (3.7 in my case)
2. netlify.toml with a custom build configuration. Here’s a gist which should get you started:

After that, it’s as simple as signing up with Netlify and connecting it to your repository. Really! Netlify comes built-in with its own CI/CD that hooks into all changes to your your source code and deploys new versions automatically. Give their docs a look to see what else you can do with them.

Bonus

A nice feature of Markdown is that it’s a superset of HTML, so all HTML code is valid. This means we have the flexibility to choose to insert some raw HTML into our docs if we have the need. Below are some extra things you can do to take your personal website to the next level.

Add a Feed for Your Medium Posts

If you’re a Medium user and you’re thinking about starting a blog, Medium is a natural choice, as it comes with a built-in audience and a fantastic CMS. However, what do you do if you also want a personal website with your blog posts made available? After a sufficient amount of research I found two viable options:

1. Write your blog posts on your website and manually import them to Medium.
2. Write your blog posts on Medium and use pixelpoint.io’s Medium widget to create a live feed of your posts.

I went with Option 2 and created a page on my website dedicated to my published posts. This option was ideal for me because it means less manual intervention in the long run. I just publish my words once and they’re available everywhere I want them to be!

Add a Contact Form

A very nice feature of Netlify is automatic detection of forms on your website and capture of the submissions. No need to spin up a database or notification system!

Forms are easy to write in HTML, but we will likely need to add additional CSS to make it look pretty. For my purposes, I wanted something that followed the same Material Design principles as the rest of the website, so I hack&pasted some CSS that does the job (credit to this pen for getting me most of the way). You can see the final result here and the source HTML here.

Including extra CSS for your site is as easy as adding the extra_css block to your mkdocs.yml, which you can see in the gist I linked above. Once you’ve done that, you’ll be all set.

Wrap Up

In this post we learned how to:

1. Set up a project with Poetry and MkDocs
2. Configure your MkDocs project.
3. Configure your project for deploying with Netlify.
4. Add a live feed for your Medium posts.
5. Add a contact form for your site.

That’s quite a lot! Now for the hard part — go write some content and make your site look like you 😎