Skip to content

Setup Mkdocs

Why?

It’s not necessary to setup Mkdocs on your client PC. BUT I recommend setup Mkdocs on your client because:

  • Avoid ill-formated Markdown description
  • Avoid error in pipeline on remote repository
  • Editor’s preview is not enough to check how your page looks

Wny need python and virtual environment?

  • For installation and running Mkdocs
  • Python virtual environment is useful for “clean” version management of dependencies in multiple python libraries

Python and virtual environment

Get python (Windows)

type python3 on your command prompt or terminal

then windows app store opens. and click “Get”, then download and install it.

Python command on gitbash (Windows)

python3 command dows not work on gitbash. 

1
2
3
tato@greenlantern MINGW64 ~
$ python3
bash: /c/Users/beiji/AppData/Local/Microsoft/WindowsApps/python3: Permission denied

Instead, py command works for Windows. 

1
2
3
4
5
tato@greenlantern MINGW64 ~
$ py
Python 3.9.1 (tags/v3.9.1:1e5d33e, Dec  7 2020, 17:08:21) [MSC v.1927 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>

Ref.[How to fix permission denied in git bash in windows10] (https://superuser.com/questions/1532831/how-to-fix-permission-denied-in-git-bash-in-windows-10)

Python virtual environment

On gitbash (Windows), 

1
2
3
4
5
$ cd "<your local repository>"
# cd ~/repo/gitlab_fab/tatsuro.homma/fabacademy
$ py -m venv env1
$ source env1/Scripts/activate
(env1)

On bash (Ubuntu, Mac OS),

In this case, making virtual environment at home directory (~/env1). Location of virtual environment depends on the project. 

1
2
3
4
5
$ cd "<your local repository>"
# cd ~/repo/gitlab_fab/tatsuro.homma/fabacademy
$ python3 -m venv ~/env1
$ source ~/env1/bin/activate
(env1)

Every library dependencies are controlled under “env1” directory.

Install Mkdocs for student template

Clone student template

Student template using Mkdocs-materials is on https://gitlab.fabcloud.org/fibasile/fabacademy-student-template

On gitbash,

1
2
3
4
$ cd "directory to locate the student template "
# cd ~/repo/gitlab_fab/tatsuro.homma/fabacademy

$ git clone git@gitlab.fabcloud.org:fibasile/fabacademy-student-template.git

Copy necessary files from student template to your repository

1
2
3
4
5
$ cp -p .gitignore ../tatsuro.homma/fabacademy/
$ cp -p .gitlab-ci.yml ../tatsuro.homma/fabacademy/
$ cp -pr docs ../tatsuro.homma/fabacademy/
$ cp -p mkdocs.yml ../tatsuro.homma/fabacademy/
$ cp -p requirements.txt ../tatsuro.homma/fabacademy/

Check python versions on virtual env

1
2
3
tato@greenlantern MINGW64 ~/repo/gitlab_fab/tatsuro.homma/fabacademy (master)
$ cd "your local repository"
# cd

On Windows 

1
2
3
4
5
6
7
$ py -V
Python 3.9.1
(env1)

$ pip -V
pip 20.2.3 from c:\users\tato\repo\gitlab_fab\tatsuro.homma\fabacademy\env1\lib\site-packages\pip (python 3.9)
(env1)

On Ubuntu or Mac

1
2
3
4
(env1) $ python --version
Python 3.6.9
(env1) $ pip --version
pip 9.0.1 from /home/tato/repo/fabcloud/fabacademy/env1/lib/python3.6/site-packages (python 3.6)

Library dependencies are specified in requirements.txt in student template. 

1
2
3
4
5
6
7
8
9
tato@greenlantern MINGW64 ~/repo/gitlab_fab/tatsuro.homma/fabacademy (master)
$ pip install -r requirements.txt
--
  Downloading smmap-3.0.5-py2.py3-none-any.whl (25 kB)
Installing collected packages: smmap, pytz, gitdb, pymdown-extensions, Pygments, mkdocs-material-extensions, GitPython, babel, mkdocs-material, mkdocs-git-revision
-date-localized-plugin
Successfully installed GitPython-3.1.12 Pygments-2.7.4 babel-2.9.0 gitdb-4.0.5 mkdocs-git-revision-date-localized-plugin-0.8 mkdocs-material-6.2.6 mkdocs-material-
extensions-1.0.1 pymdown-extensions-8.1.1 pytz-2020.5 smmap-3.0.5
(env1)

You can check installed library packages by:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
$ pip list
Package    Version
---------- ----------
click      7.1.2
future     0.18.2
Jinja2     2.11.2
joblib     1.0.0
livereload 2.6.3
lunr       0.5.8
Markdown   3.3.3
MarkupSafe 1.1.1
mkdocs     1.1.2
nltk       3.5
pip        21.0
PyYAML     5.4.1
regex      2020.11.13
setuptools 49.2.1
six        1.15.0
tornado    6.1
tqdm       4.56.0
(env1)

Update .gitignore file

Warning

Before you git add . or git commit to your local repository, add “env1” (python virtual environment directory specified above) to .gitignore file. Nevertheless bunch of python execution libraries will be uploaded to local/remote repository.

.gitignore

1
2
3
4
5
.env
_site
.DS_Store

env1

Run mkdocs

On gitbash or terminal on Mac/Ubuntu, change directory to yoru local repository

1
2
$ cd "your local repository path"
# (e.g. cd ~/repo/gitlab_fab/tatsuro.homma/fabacademy)

Then run mkdocs serve (on virtual environment if you have not enterred)

On Mac/ubuntu: 

1
$ source ~/env1/bin/activate

On gitbash 

1
$ source env1/Scripts/activate

Then run mkdocs by mkdocs serve

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" c
onfiguration:
  - tips\client\wsl2_install.md
INFO    -  Documentation built in 1.62 seconds
[I 210129 12:17:08 server:335] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 210129 12:17:08 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 210129 12:17:08 handlers:64] Start detecting changes
INFO    -  Start detecting changes

Now you can see how your page looks on your browser on http://127.0.0.1:8000

Last update: June 24, 2021