How to install mkdocs in Ubuntu server 18.04

Share this post to your friends !

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.

# mkdocs serve -a 127.0.0.1:8000

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

https://ip-server-dev:8000

Conclusion

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.

If you liked this article, then please subscribe to our YouTube Channel for more video tutorials. You can also find us on Twitter and Facebook.


Share this post to your friends !
If you appreciate what we share in this blog, you can support us by:
  1. Stay connected to: Facebook | Twitter | Google Plus | YouTube
  2. Subscribe email to recieve new posts from us: Sign up now.
  3. Start your own blog with SSD VPS - Free Let's Encrypt SSL ($2.5/month).
  4. Become a Supporter - Make a contribution via PayPal.
  5. Support us by purchasing Ribbon Lite Child theme being using on this website.

We are thankful for your support.

«« »»

Got something to say? Join the discussion

Please keep in mind that all comments are subject to our Comment Policy. Your email address will not be published.
This site uses Akismet to reduce spam. Learn how your comment data is processed.