Publish a Static Website in a Day with MkDocs and Netlify

Sean Stewart
Jan 13 · 6 min read
Image for post
Image for post


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 😱.


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

  1. Mobile-friendly.
  2. Easy to update.
  3. Simple to deploy.


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
  1. 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.
  2. pymdown-extensions: An optional markdown plugin which adds a whole host of useful markdown extensions which we’ll configure later in this tutorial.
  3. fontawesome-markdown: An optional markdown plugin which adds native support for font-awesome glyphs directly within your markdown using the same syntax as emojis.
Create a new virtualenv and install the dependencies

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. 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.
  2. Simple, transparent configuration with mkdocs.yml.
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.

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:

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. netlify.toml with a custom build configuration. Here’s a gist which should get you started:


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 Medium and use’s Medium widget to create a live feed of your posts.

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!

Wrap Up

In this post we learned how to:

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

The Startup

Medium's largest active publication, followed by +729K people. Follow to join our community.

Sean Stewart

Written by

New York based Software Engineer and Fiction writer.

The Startup

Medium's largest active publication, followed by +729K people. Follow to join our community.

Sean Stewart

Written by

New York based Software Engineer and Fiction writer.

The Startup

Medium's largest active publication, followed by +729K people. Follow to join our community.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store