Skip to content

Building this Blog Site

Quick Overview

This blog is built using Material for MkDocs, repo on GitHub and hosted on Netlify. That's it! I create the markdown files locally, build the site and push the changes to my repo on GitHub. Netlify picks up the changes and my new blog site is live and updated.

Ingredients

This is what you'll need to make this:

Locally

  1. Python==3.8: https://www.python.org/
    This was the most recent at the time I wrote this. 3.9 was just about to drop.

    1
    python --version

    Note

    Currently OSX comes with Python 2.7 which is no longer supported. You should be using Python 3.x. I would recommend installing Python 3 using Homebrew. This will enable you to easily upgrade to the versions as they are released by uninstalling the old one and brewing the new version.

  2. Pip>=20.1: https://pip.pypa.io/en/stable/reference/pip_install/
    Package Manager for Python. Comes with Python

    1
    pip --version

  3. mkdocs==1.1.2: https://www.mkdocs.org/#installation
    Simple pip install for this.

    1
    mkdocs --version

  4. mkdocs-material==5.2.0: https://squidfunk.github.io/mkdocs-material/getting-started/
    Simple pip install for this.

    1
    pip3 list | grep mkdocs-material

  5. mkdocs-material-extensions==1.0:
    This comes installed with mkdocs.

    1
    pip3 list | grep mkdocs-material

  6. VS Code>=1.45.1: https://code.visualstudio.com/
    Doesn't really matter what version you run here. You could just use a simple text editor

    1
    code --version

  7. Git>=2.21.1: https://git-scm.com/
    This is the version that comes installed on your Mac. I'm runnig OSX Catalina 10.15.4

    1
    git --version

Globally

  1. GitHub: https://github.com/
    Create an account (if you don't already have one). This will be the repository for the source code for your site.

  2. Netlify: https://www.netlify.com/
    Signup for a Netlify account. Currently they are free which is totally amazing. This is where your final site files will be hosted.

Putting it all together

  1. Create a repo on your new github account. Follow the prompts to create a new folder locally and connect it to your repo in github

  2. Follow the instructions on mkdocs to start a new project. https://www.mkdocs.org/#installation

  3. Add some markdown content.

    1
2
3
4
5
6
7
    # To view the site while you are editing:
mkdocs serve
# by default you will be able to view the website on: http://127.0.0.1:8000

# Build the site:
mkdocs build
# This creates the actual static files and places them in the 'sites' folder

  4. Commit and Push to github

    1
2
3
4
5
6
7
8
    # Add changed files the staged list
git add *

# Commit these staged files with a comment
git commit -m "Initial Commit to start this project"

# Push the changes to github
git push

  5. Now we setup Netlify
    Create your account or login if you already have one.

    Now we want to create a new site from git.
    Netlify

    Select GitHub and follow the prompts to connect to your github account and select your new repo that we created above.
    Netlify

    Now we just need to specify the directory to publish which is the site folder that mkdocs created for us. It is in the root path in your github repo so all you have to do is type site in the Publish Directory form field and click deploy. Netlify

    If you don't like the funky domain name that Netlify creates for your new site then you can add your own custom domain. Navigate to Domains and select Add domain alias enter your preferred name and click OK. Netlify

    Go to your domain registry where you can add a CNAME record to point to your new Netlify site. To know what you need to add in the CNAME record just copy the contents from the Check DNS configuration button in your Netlify portal.
    Netlify