How to deploy a static site using Mkdocs and Netlify

MkDocs is an open-source static site generator that is used to create documentation websites. It is written in Python and is built on top of the Jinja2 template engine. It uses Markdown files as the source for the documentation, and it generates a static HTML website that can be hosted on any web server.

Why is Mkdocs so popular?

MkDocs is a great tool for creating professional-looking documentation websites for your projects, and it’s widely used in open-source communities and enterprise organizations.

MkDocs allows you to easily organise your documentation into sections and pages and supports features like search, navigation, and theme customisation. It also provides a built-in development server that lets you preview your documentation while working on it.

What is Netlify and how it works?

Netlify is a popular static site hosting serverless platform. It is a popular way to build, deploy, and scale modern web applications in a much more scalable and secure way.

Netlify helps developers to launch websites and campaigns in minutes with no fuss. Netlify is built primarily for JAMstack sites, which unify JavaScript and APIs to allow applications that are well suited for both developers and content editors.

The developer writes code and stores it in a version control repository (e.g. GitHub).
When a new change is merged into the main branch of the repository, a webhook notifies Netlify to deploy a new site.
Netlify pulls the latest version of the app from the repository and runs a build command to generate the static site files
Netlify then uses Plugins and internal code to make adjustments to your site, pre-render all of your pages in static HTML and improves it further /
Once the build process gets completed, Netlify takes the static assets and pushes them to its global CDN for fast delivery.

How does Mkdocs and Netlify work together?

MkDocs and Netlify work together to create and deploy a static documentation website. Here is how the process typically works:

You create your documentation using Markdown files and organize them into sections and pages using MkDocs.
You run the command mkdocs build to generate a static HTML website from the Markdown files.
You push the generated HTML website and your source files to a source control repository (e.g. GitHub, GitLab, Bitbucket)
You set up a new site in Netlify and connect it to your source control repository.
You configure the build settings in Netlify to run the command mkdocs build and specify the output directory as the publish directory.
When you push changes to your source control repository, Netlify will automatically build and deploy the updated documentation website.

This way, you can easily manage your documentation in Markdown and preview it locally with the built-in development server of mkdocs. And when you’re ready to deploy it, you can push it to your source control repository and let Netlify handle the build and deployment process.

With this setup, you can easily make updates to your documentation and deploy them to your website without needing to manually upload files or configure a web server.

It’s also worth mentioning that you can use Netlify’s caching feature to speed up the build process and to make sure that your site is served as quickly as possible.

Getting Started

Prerequisite

Apple Mac/Linux/Windows
A GitHub Account
A Netlify Account
GitHub Repository configured with Netlify
Python 3.6

Step 1. Installing Mkdocs

MkDocs can be easily installed via pip and configured using a simple YAML configuration file. It also provides a command-line interface (CLI) that allows you to build, preview, and deploy your documentation with a few simple commands.

To install MkDocs, run the following command from the command line:

pip install mkdocs

Step 2. Creating a new project

Getting started is super easy. To create a new project, run the following command from the command line:

mkdocs new dockerlabs
cd dockerlabs

There’s a single configuration file named mkdocs.yml, and a folder named docs that will contain your documentation source files (docs is the default value for the docs_dir configuration setting). Right now the docs folder just contains a single documentation page, named index.md.

MkDocs comes with a built-in dev-server that lets you preview your documentation 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
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

Customising your site

Now that we’ve got a basic site set up with MkDocs, it’s time to customize the site.

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

Naming your Site

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

site_name: DockerLabs

Add pages to Site

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

site_name: Collabnix
site_url: https://dockerlabs.collabnix.com/
nav:
    - Home: index.md

Theme your Site

Add a theme setting:

site_name: Collabnix
site_url: https://dockerlabs.collabnix.com/
nav:
    - Home: index.md
    - Installation:
      - Installing Docker Desktop for Linux: docker-desktop-for-linux.md
      - Installing Docker Desktop for Windows: docker-desktop-for-windows.md
      - Installing Docker Desktop for Mac: docker-desktop-for-mac.md
      - Installing Docker on Raspberry Pi: docker-on-raspberrypi.md
      - Installing Docker on NVIDIA Jetson: docker-on-jetson-nano.md
    - Getting Started with Docker Hub:
      - Creating Your Docker Hub Account: docker-hub.md
    - Getting Started with Docker Image:
      - Running Hello World Example: hello-world.md
      - Working with Docker Image: working-with-docker-image.md
      - Saving Images and Containers as tar files: saving-images-and-containers.md
      - Building Your First Alpine Docker Image: building-first-alpine.md
theme: readthedocs

Building Your Site

mkdocs build

Step 3. Accessing the static site

Visit http://localhost:8000 to access the site.

Step 4. Deploying it to Netlify

First, we need to initialize a new Python project. We will be using Poetry. Poetry is a dependency management tool and packaging system for Python. It allows developers to manage their project dependencies and package their projects for distribution, similar to tools like pip and virtualenv.

“poetry init” is a command used in the terminal to initialize a new Python project with Poetry. When you run the command “poetry init” in the terminal while in a directory, it will create a new directory with the same name as the current one and initialize a new Python project in it with Poetry. This command will also create a new file called “pyproject.toml” which is used to specify the dependencies for the project. Additionally, “poetry init” can also be used to convert an existing Python project to use Poetry by generating a pyproject.toml file.

poetry init

This command will guide you through creating your pyproject.toml config.

Package name [dockerlabs]:  dockerlabs
Version [0.1.0]:  1.0.0
Description []:  
Author [Ajeet Singh Raina <ajeetraina@Docker-Ajeet-Singh-Rainas-MacBook-Pro.local>, n to skip]:  
License []:  MIT
Compatible Python versions [^3.10]:  

Would you like to define your main dependencies interactively? (yes/no) [yes] yes
You can specify a package in the following forms:
  - A single name (requests): this will search for matches on PyPI
  - A name and a constraint (requests@^2.23.0)
  - A git url (git+https://github.com/python-poetry/poetry.git)
  - A git url with a revision (git+https://github.com/python-poetry/poetry.git#develop)
  - A file path (../my-package/my-package.whl)
  - A directory (../my-package/)
  - A url (https://example.com/packages/my-package-0.1.0.tar.gz)

Package to add or search for (leave blank to skip):

Add the packages listed below one by one:

mkdocs: The static site generator — required for this tutorial.
mkdocs-material: An optional mkdocs extension which generates your site using Material Design.
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.

This command will create a new file called pyproject.toml as shown:

cat pyproject.toml 
[tool.poetry]
name = "docker"
version = "0.1.0"
description = ""
authors = ["Ajeet Singh Raina <ajeetraina@Docker-Ajeet-Singh-Rainas-MacBook-Pro.local>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.8"
mkdocs = "^1.4.2"
mkdocs-material = "^9.0.5"
pymdown-extensions = "^9.9.1"
fontawesome-markdown = "^0.2.6"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Step 5. Installing Python Dependencies

The poetry install command is used to install the dependencies of a Python project managed with Poetry. When you run “poetry install” in the terminal, Poetry will look for a pyproject.toml file in the current directory and use the information in that file to install the specified dependencies for the project. The command will install the dependencies in the virtual environment created by Poetry for the project, so the dependencies will not conflict with other projects on your system.

By default, “poetry install” will install the dependencies in the ‘production’ environment, but you can also specify to install in the ‘development’ environment by running “poetry install –dev”
Additionally, If you have made changes to your dependencies, you can use the command “poetry update” to update the dependencies to the latest version that satisfies the constraints in your pyproject.toml file.

 poetry install

Step 6. Adding runtime.txt

You will need to specify the version of Python.

cat runtime.txt
3.8

Step 7. Create netlify.toml

Create a new file called netlify.toml with the following entries:

cat netlify.toml 
[build]
publish = "site"
command = """
pip3 install -q poetry &&
poetry config virtualenvs.in-project true &&
poetry install -v &&
mkdocs build -d site
"""

publish = “site” command = “”” pip3 install -q poetry && poetry config virtualenvs.in-project true && poetry install -v && mkdocs build -d site “””

Step 8. Pushing the changes to GitHub

Run the below steps to push it to Github

 git add .
 git commit -m "Added project"
 git push

Step 9. Accessing Netlify UI

Visit Netlify and ensure that the site gets built without any issue.

Step 10. Accessing the Prod Site

visit https://dockerlabs.netlify.app to access the site