Technical Documentation via MkDocs

Introduction: This article explains about writing technical documentation using Mkdocs, installation, update and deployment on production.

Installation: Follow these steps to setup Mkdocs on your local machine and run its dev server.

Install Python by downloading an installer appropriate for your system from python.org and running it.

1. Install mkdocs package using the following command pip install mkdocs
2. You should now have the mkdocs command installed on your system. Run mkdocs --version to check that everything worked okay.
3. Use the following command to start the server mkdocs serve --dev-addr=127.0.0.1:8080.

Note: The --dev-addr switch is optional and need only be used to change the port on which the server is run.

The dev server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes

Adding or updating documents: Follow these steps to make create new documents or update existing ones.

1. Setup a new repository on your version control(e.g. github, gitlab etc…).
2. Every technical documents must be written in markdown format (.md) and added to the docs folder.
3. Follow the appropriate directory structure to store documents.

4. Update the mkdocs.yml file to add reference to your new page.

5. Start the dev server to make sure everything compiles, and the document is properly formatted and linked.

6. Create a merge request for your changes.

Deployment via Docker: Setup the Jenkins pipeline so that whenever the merge request has been accepted deploy it on server so that everyone can access the documentation as html.

.htpasswd

root:$passw0rd

Shell Script

chmod a+x $WORKSPACE
mkdocs build

DockerFile

FROM nginx

COPY nginx.conf /etc/nginx/nginx.conf
COPY .htpasswd /etc/nginx/.htpasswd

WORKDIR /usr/share/nginx/html
COPY site/ .

nginx.conf

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    server {
        listen 80;
        server_name  localhost;

	auth_basic           "Restricted area";
	auth_basic_user_file /etc/nginx/.htpasswd;

        root   /usr/share/nginx/html;
        index  index.html index.htm;
        include /etc/nginx/mime.types;

        location / {
            try_files $uri $uri/ /index.html;
        }
    }
}

Customization:: To customize more features like icon, theme etc… follow their official guideline. https://www.mkdocs.org/getting-started/#getting-started-with-mkdocs