Home » Linux Tutorials » How to install mkdocs in Ubuntu server 18.04

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
    sys.exit(cli())
  File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python2.7/dist-packages/mkdocs/__main__.py", line 134, in serve_command
    livereload=livereload
  File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/serve.py", line 124, in serve
    _livereload(host, port, config, builder, site_dir)
  File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/serve.py", line 36, in _livereload
    from livereload import Server
  File "/usr/local/lib/python2.7/dist-packages/livereload/__init__.py", line 15, in
    from .server import Server, shell
  File "/usr/local/lib/python2.7/dist-packages/livereload/server.py", line 20, in
    from tornado.wsgi import WSGIContainer
  File "/usr/local/lib/python2.7/dist-packages/tornado/wsgi.py", 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
/home/venv/bin/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:
  - concepts.md

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 http://127.0.0.1:8000
[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 127.0.0.1 to your IP, 8000 to your Port.