MkDocs

Access

• Open: http://SERVER_IP

Edit & Publish Content

1. Add or edit Markdown files: /opt/mkdocs/docs

2. If you add or rename pages, update /opt/mkdocs/mkdocs.yml for navigation.

3. Rebuild the site:

/opt/mkdocs/venv/bin/mkdocs build --clean \
  --config-file /opt/mkdocs/mkdocs.yml \
  --site-dir /opt/mkdocs/site

Nginx serves the generated files from: /opt/mkdocs/site

No Nginx restart is required after rebuilding.

Important Paths

• Project: /opt/mkdocs
• Content: /opt/mkdocs/docs
• Configuration: /opt/mkdocs/mkdocs.yml
• Build output: /opt/mkdocs/site
• Python virtual environment: /opt/mkdocs/venv
• MkDocs executable: /opt/mkdocs/venv/bin/mkdocs
• Nginx configuration: /etc/nginx/sites-available/mkdocs.conf

Domain & HTTPS

1. Point your domain to the server's IP address.

2. Edit Nginx config and replace server_name _; with your domain (e.g., server_name <YOUR_DOMAIN>;):

vim /etc/nginx/sites-available/mkdocs.conf

3. Test the configuration:

nginx -t

4. Install Certbot:

apt install -y certbot python3-certbot-nginx

5. Generate a Let's Encrypt certificate:

certbot --nginx --non-interactive --agree-tos --email <YOUR_EMAIL> -d <YOUR_DOMAIN>

6. Reload Nginx:

systemctl reload nginx

7. Update the MkDocs site URL: replace site_url: 'http://<SERVER_IP>/' with site_url: 'https://<YOUR_DOMAIN>/' in /opt/mkdocs/mkdocs.yml.

8. Rebuild the site:

/opt/mkdocs/venv/bin/mkdocs build --clean \
  --config-file /opt/mkdocs/mkdocs.yml \
  --site-dir /opt/mkdocs/site

9. Open your browser and visit: https://<YOUR_DOMAIN>

Notes

• Markdown changes must be rebuilt before they appear on the public website.
• Nginx serves the generated files from /opt/mkdocs/site.
• Change mkdocs.yml and the project configuration based on your preferences.