Deploying Static Website with MkDocs and Netlify

I recently got around to publishing our technical thought leadership website and the whole experience was so delightful I felt it important to share my experience. 😀

Background 🤔

In my career until this point, I never focused on front-end framework. I have almost zero experience with front-end framework, having largely focused on back-end web-services and data science, Machine Learning. While there are may tutorials on how to develop website using the different flavours of js, but I was unsure wheather to invest my time in these technologies as understanding and implementating will take time.

However, I recently came across two components that together seemed to fast: 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 Git provider with a very good free offering.

Set up MkDocs 🛠️

To use MkDocs, you’ll need Python 3.6+ installed on your system, as well as the Python package manager, pip.

While you install MkDocs, you should also pick a theme. Here, we picked the material theme. Thanks to Martin Donath!

Installation

$ pip install --upgrade pip
$ pip install mkdocs
$ pip install mkdocs-material
$ pip install pymdown-extensions
---> 100%
Successfully installed mkdocs, mkdocs-material

Create New Site

Now we are ready to create new project, run the blow command to create a new project.

$ mkdocs new website
---> 100%
INFO    -  Creating project directory: website
INFO    -  Writing config file: website\mkdocs.yml
INFO    -  Writing initial docs: website\docs\index.md

There’s a single configuration file named mkdocs.yml, and a folder named docs that will contain your documentation source files.

|   mkdocs.yml
|
\---docs
        index.md

Preview your Site

MkDocs comes with a built-in devlopment server that lets you preview your website as you work on it.

Make sure you’re in the same directory as the mkdocs.yml configuration file, and then start the server by running the mkdocs serve command:

$ mkdocs serve
---> 100%
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 1.11 seconds
[I 210318 18:05:32 server:335] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000

Customize your Site 🎨

Now that we’ve got a basic site set up with MkDocs, we can get to the amazing part, actually putting together a website!

Open mkdocs.yaml and you will able to add below:

Name your Site

Change the site_name setting to “Nilesh Dalvi” and save the file.

site_name: Nilesh Dalvi

Add pages to Site

Add an order, title, and nesting of each page in the navigation header by adding a nav setting:

site_name: Nilesh Dalvi
nav:
    - Welcome: index.md
    - About: about.md

Theme your Site

Add a theme setting:

site_name: Nilesh Dalvi
nav:
    - Welcome: index.md
    - About: about.md
theme:
    name: 'material'
    palette:
        primary: 'blue'

Emojify your Site

The Emoji extension, which is part of Python Markdown Extensions, adds the ability to integrate emojis and icons in the *.svg file format

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

Design index page

Imagine that, you want to create your own personal website then this is what we will write in index.md. If you’re unfamiliar with .md files, you can learn more about the syntax here. :

# Nilesh Dalvi

## Me :smile:

![This is what I look like](https://s.gravatar.com/avatar/e7d500f9792a234cff852fbe34351616?s=80)

A quick run-down about me: :wave:

:computer: I like to code in Python :snake:

:technologist: I am Data Scientist @ PMAM

:man_teacher: Teaching is my passion

Build your Site ⚙️

That’s looking good. You’re ready to deploy your site. First build the site:

$ mkdocs build
---> 100%
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: website\site
INFO    -  Documentation built in 0.78 seconds

This will create a new directory, named site

Look at that your source markdown has been converted to HTML files here.

Deploy your Site 🚀

The site that you just built only uses static files so you’ll be able to host it anywhere.

Deploy Site on your private web space

Upload the contents of the entire site directory to wherever you’re hosting your website from and you’re done.

Deploy Site on Netlify

Netlify is a fantastic hosting solution that is easy to set up and a very good free tier.

They also provide a DNS service and TLS for your custom domains.

To host your site on Netlify, Add these three files to the root of your project:

• requirements.txt: this will list software dependencies and versions.
• runtime.txt: tell Netlify which Python version to use.
• netlify.toml: contains some site settings.

In my files, I have the following:

# requirements.txt
mkdocs
mkdocs-material
pymdown-extensions

# runtime.txt
# don't specify a patch version, such as 3.7.6
3.7

# netlify.toml
[build]
  command = "mkdocs build"
  publish = "site"

Now you can deploy as usual, Follow a basic continuous deployment pipeline:

1. Push your changes to your remote repo (GitHub / GitLab / Bitbucket) and merge to master, or your deployment branch.

2. In Netlify, select New site from Git and walk through the process to deploy with git.

And that should be it. Your site should build, and be available at a preview link

Conclusion 👍

Here we learned how to:

1. Set up required environment for MkDocs.

2. Configure your MkDocs project.

3. Customize and Configure Your Site

4. Configure your project for deploying with Netlify.

Happy Learning! 😀