How to install mkdocs in Ubuntu server 18.04

by Daniel Pham
Published: Updated:

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.

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.

(This is an article from my old blog that has been inactive for a long time, I don’t want to throw it away so I will keep it and hope it helps someone).

0 0 votes
Article Rating

You may also like

Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments

DevOps Lite is a personal blog specializing in technology with main topics about DevOps, DevSecOps, SRE and System Administrator. Articles are shared for free and contributed to the community.

SUPPORT US

FOLLOW US

Subscribe my Newsletter for new blog posts. Stay updated from your inbox!

© 2021-2024 DevOpsLite.com – All rights reserved.

Please write sources “DevOpsLite.com” when using articles from this website.

This website uses cookies to improve your experience. We'll assume you're ok with this, but you can opt-out if you wish. Accept Read More

2
0
Would love your thoughts, please comment.x
()
x

Adblock Detected

Please support us by disabling your AdBlocker extension from your browsers for our website.