The Startup
Published in

The Startup

Publish a Static Website in a Day with MkDocs and Netlify



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


Create the Source

Set Up Your Environment

Create your project directory and initialize with poetry
  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.
Create a new virtualenv and install the dependencies

Initialize MkDocs

  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.
Initialize the mkdocs project scaffolding and turn on the server

Customize and Configure Your Site

Read the Docs

Add Some Extras

Deploy Your Site on Netlify

  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:


Add a Feed for Your Medium Posts

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

Add a Contact Form

Wrap Up

  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.



Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +768K followers.

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