How to install mkdocs in Ubuntu server 18.04

SystemMen - How to install mkdocs in Ubuntu server 18.04? MkDocs is a simple tool for building project documents. It uses markdown-style source documents and builds them into HTML documents.

In this article, I will not guide you how to write markdown documents. I will guide you to install mkdocs in Ubuntu 18.04 and use it to build project documents.

how-to-install-mkdocs-in-ubuntu-server-18-04 How to install mkdocs in Ubuntu server 18.04
Install MkDocs in Ubuntu server 18.04.

Check the software version

We will install mkdocs through python & pip, so we will check the version information with the following commands.

root@dev:/home# python --version
Python 2.7.12
root@dev:/home# pip --version
pip 8.1.1 from /usr/lib/python2.7/dist-packages (python 2.7)

If you use a slightly different version is okay.

Install MkDocs in Ubuntu 18.04

If your server does not have pip installed, run the following command to install it.

# apt-get install python-pip -y

Next, to avoid the following error.

Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 11, in
  File "/usr/local/lib/python2.7/dist-packages/click/", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python2.7/dist-packages/click/", line 717, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python2.7/dist-packages/click/", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python2.7/dist-packages/click/", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python2.7/dist-packages/click/", line 555, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python2.7/dist-packages/mkdocs/", line 134, in serve_command
  File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/", line 124, in serve
    _livereload(host, port, config, builder, site_dir)
  File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/", line 36, in _livereload
    from livereload import Server
  File "/usr/local/lib/python2.7/dist-packages/livereload/", line 15, in
    from .server import Server, shell
  File "/usr/local/lib/python2.7/dist-packages/livereload/", line 20, in
    from tornado.wsgi import WSGIContainer
  File "/usr/local/lib/python2.7/dist-packages/tornado/", line 51
    def to_wsgi_str(s: bytes) -> str:
SyntaxError: invalid syntax

I recommend you to use virtualenv for the mkdocs environment.

We will install virtualenv with the following command.

# pip install virtualenv

Next, we create a virtualenv directory.

# virtualenv venv

Run the virtualenv environment.

# source venv/bin/activate

Now, in my case I use mkdocs 1.0.4, so I will use the command below to install it.

(venv) root@dev:/home# pip install mkdocs==1.0.4

After installing mkdocs, you can run the following command to see if it has been installed correctly into the virtualenv environment.

(venv) root@dev:/home# which mkdocs

And now, you clone your document source to the server. Use the following command to build the document, example your source in folder name source.

(venv) root@dev:/home# mkdocs build

If the outcome is as successful as mine, congratulations.

(venv) root@dev:/home/source# mkdocs build
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/source/site 
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:

Now, you need to run the service so that it can provide documents that can be accessed as HTML web with the following command, note that it is still in a virtualenv environment.

(venv) root@dev:/home/source# mkdocs serve
INFO    -  Building documentation… 
INFO    -  Cleaning site directory 
[I 191104 20:56:14 server:296] Serving on
[I 191104 20:56:14 handlers:62] Start watching changes
[I 191104 20:56:14 handlers:64] Start detecting changes

If you want to run with specified IP and Port, you can use the following command. Edit to your IP, 8000 to your Port.

# mkdocs serve -a

You can now access this link in a web browser to view it.



In the next article, I will show you how to use the Supervisor to manage the mkdocs service. Hope this article is helpful to you.

«« »»