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.
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
(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.
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.
If you appreciate what we share in this blog, you can support us by:
- Stay connected to: Facebook | Twitter | Google Plus | YouTube
- Subscribe email to recieve new posts from us: Sign up now.
- Start your own blog with SSD VPS - Free Let's Encrypt SSL ($2.5/month).
- Become a Supporter - Make a contribution via PayPal.
- Support us by purchasing Ribbon Lite Child theme being using on this website.
We are thankful for your support.