Build Personal Site with MkDocs¶

As I’m a newbie in this field, I’m going to prioritize what makes my documentation process as easy as possible. Therefore, for my documentation, I’m going to stick using Markdown.

There are some static site generator that can work with Markdown. But I found Mkdocs is built specifically for Markdown uses. Therefore, I will try to explore Mkdocs for now.

Step 1: Install Mkdocs Material¶

For first practice, I will be using Material for Mkdocs. Material for MkDocs is a theme template, built on top of Mkdocs. It gives pretty modern and clean looks that you can easily customized. I followed this tutorial to set up my dummy site.

Check Python and Pip¶

Since Material for Mkdocs is published as a Python package, it needs to be installed with a package manager. Here, it’s recommended to use pip, the Python package manager, with a conditon that python needs to be installed beforehand. Python and pip are usually pre-installed in mac.

👉 Open terminal and run:

python --version

w1-1

At first, it was giving error message that python was not found on my laptop.

👉 Then, I tried typing pip to check if pip was installed by any chance.

pip --version

w1-2

Same result, pip was also not found.

👉 With the help of my colleague, Eka, he suggested to run python3 instead.

w1-3

Apparently, it works with this command! So, I have Python 3.9.6 pre-installed on my mac, but not pip.

Install pip¶

Based on this tutorial, if you’re installing pip for the first time, you need to download get-pip.py and then run this commmand:

python get-pip.py

w1-4

But it’s giving error messages again, I think it’s because at this point, I haven’t downloaded the get-pip code yet.

Eka helped me with another approach, which is to copy and paste the code directly to the Terminal. To do this, we need to open the terminal’s text editor by running the following command

nano get-pip.py

It will open up the editor box. Copy all the text from the get-pip.py and paste it to the nano box.

w1-6

Click ‘ctrl + X’ to close. It will ask if we’d like to save the edits or not. Click Y to save.

Now that I got the pip in my directory, I can finally run the command to install pip:

python3 get-pip.py

Finally, pip successfully installed! Now, onto the next step!

Install Mkdocs Material¶

To install Mkdocs Material, open terminal, and write this command:

pip install mkdocs-material

However, in my case, although pip was successfully installed, the script was not on PATH (as highlighted in the yellow text), thus the terminal couldn’t read it. 😞

w1-8

Therefore, instead of just writing ‘pip’, I had to write the whole path name, with ‘~’ in the begininng’, which becomes ‘~/Library/Python/3.9/bin/pip’. The symbol ‘~’ basically means run from ‘that’ directory.

But worry not, my Mkdocs Material was successfully installed! It’s just that I have to refer ‘mkdocs’ by its path name, ‘/Library/Python/3.9/bin/mkdocs’, because of that path problem.

Step 2: Setting up a Dummy Site¶

Create New Dummy Repository at Gitlab¶

For experimentation of making our own dummy site, I have to make a dummy central repository by creating a new project on gitlab.

w1-9

Clone remote (dummy) repository to local¶

And then clone the repository locally by following the steps mentioned in the Task 1 Seting Up Git.

Since this dummy site is made from scratch, for the next steps, I followed this tutorial by Mkdocs material to configure up the site setup.

Create and Configure Site¶

Open the file in VSCode.

Open Terminal
Make new folder by writing
mkdocs new

w1-39 mkdocs new

It will create a new docs folder looking like this

w1-40

Previewing as you write¶

To be able to see how your site will looks like, there’s a command which allows you to preview on the go. To activate it, write:

    mkdocs serve

and to see the resulted preview, type localhost:80000 on the browser

w1-41

I personally love this command very much! Because sometimes what’s seen on the VSCode preview box will translate differently to the one that is built by the site.

Enable material theme¶

For minimal configuration to get started, add the following lines at the mkdocs.yml file:

    theme:
        name: material

w1-42

Build site¶

After done editing, we can fabricate our site by running this command:

    mkdocs build

Once the building process finsihed, thehere should be a site folder containing some html files

w1-44 build

Add and Edit README file¶

Since this is a dummy site, we should also set our README.md file

create new file under docs folder, named README.md

write some content. Inthis case, I just copied the README file template at our gilab account

Alt text

Publish Site¶

.gitlab-ci.yml¶

Deploying our site to Gitlab made possible by using Gitlab CI task runner. To enable it,

Create a new task definition file under docs folder, named .gitlab-ci.yml
Copy paste the following lines to the file

pages:
  stage: deploy
  image: python:latest
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'