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:
- Clean, accessible design.
- Easy to update.
- Simple to deploy.
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.
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.
Note in the animation above I’ve defined the following dependencies:
- mkdocs: The static site generator — required for this tutorial.
- 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.
- pymdown-extensions: An optional markdown plugin which adds a whole host of useful markdown extensions which we’ll configure later in this tutorial.
- 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
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 truebefore running
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:
- Your docs are written in Markdown, which is a gold-standard, cross-platform text markup with fantastic support.
- 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.
- Simple, transparent configuration with
Initializing a mkdocs-based website is extraordinarily simple:
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
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:
runtime.txtcontaining your Python version (3.7 in my case)
netlify.tomlwith 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.
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:
- Write your blog posts on your website and manually import them to Medium.
- 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.
In this post we learned how to:
- Set up a project with Poetry and MkDocs
- Configure your MkDocs project.
- Configure your project for deploying with Netlify.
- Add a live feed for your Medium posts.
- 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 😎