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

1$ pip install --upgrade pip
2$ pip install mkdocs
3$ pip install mkdocs-material
4$ pip install pymdown-extensions
5---> 100%
6Successfully installed mkdocs, mkdocs-material

Create New Site

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

1$ mkdocs new website
2---> 100%
3INFO    -  Creating project directory: website
4INFO    -  Writing config file: website\mkdocs.yml
5INFO    -  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.

1|   mkdocs.yml
2|
3\---docs
4        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:

1$ mkdocs serve
2---> 100%
3INFO    -  Building documentation...
4INFO    -  Cleaning site directory
5INFO    -  Documentation built in 1.11 seconds
6INFO    -  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.

Add pages to Site

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

1site_name: Mr.yang's wiki
2nav:
3    - Welcome: index.md
4    - About: about.md

Theme your Site

Add a theme setting:

1site_name: Mr.yang's wiki
2nav:
3    - Welcome: index.md
4    - About: about.md
5theme:
6    name: 'material'
7    palette:
8        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

1markdown_extensions:
2  - pymdownx.emoji:
3      emoji_index: !!python/name:materialx.emoji.twemoji
4      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. :

 1# Mr.yang
 2
 3## Me :smile:
 4
 5A quick run-down about me: :wave:
 6
 7:computer: I like to code in Python :snake:
 8
 9:technologist: I am SA
10
11:man_teacher: Teaching is my passion

Build your Site ⚙️

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

1$ mkdocs build
2---> 100%
3INFO    -  Cleaning site directory
4INFO    -  Building documentation to directory: website\site
5INFO    -  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:

1# requirements.txt
2mkdocs
3mkdocs-material
4pymdown-extensions

we can give the package version, like this mkdocs==1.5.3. we can use the command pip freeze > requirements.txt get all packages version.

1# runtime.txt
2# don't specify a patch version, such as 3.7.6
33.7

I am using is python 3.10 version, but testing found that netlify only supports 3.8 currently.

1# netlify.toml
2[build]
3  command = "mkdocs build"
4  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.