2025-05-31 2:35:56 PM

Status:

Tags:

Ubuntu Server 24.04.2 LTS Linux

venv Instructions (I'm using these)

[!NOTE] Note This assumes that you have already installed MkDocs. Also, I'm setting up MkDocs on an Ubuntu server that already has Nginx installed and running.

I will be hosting this on a subdomain called docs.bitwyre.cc.

To create a new project, first navigate to the directory where MkDocs lives and activate your venv:

cd ~/knowledge-base
source .venv/bin/activate

Run the following command to create the project:

mkdocs new my-project
cd my-project

The project folder structure looks like this:

![[Pasted image 20250531144805.png]]

MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as mkdocs.yml and then run this command:

mkdocs serve

Navigate to http:127.0.0.1:8000 to see the site. I couldn't do this since I was on Ubuntu Server with no GUI. So, I pressed Ctrl + c to stop it and reran it like this to listen on all available network interfaces instead of just the localhost:

mkdocs serve --dev-addr=0.0.0.0:8000

Then, I could access it from another LAN machine's browser at: http://172.28.3.3:8000 . Replace the IP address with whatever your server's LAN address is. Make sure you're specifying http and not https.

Place any Markdown (.md) files you want to serve in the ~/knowledge-base/my-project/docs/ directory.

By default, if you place a loose .md file in there, it will appear as a new tab. For example, I put Installing TIDAL.md in the docs directory and now the site looks like this:

![[Pasted image 20250531150719.png]]

You can create additional directories in the docs directory if you want fewer tabs. For example, I put that .md file in a subdirectory called Linux and now it looks like this:

![[Pasted image 20250531150921.png]]

Next, to change the browser tab header from My Docs to whatever you like, edit this file:

sudo nano ~/knowledge-base/mkdocs.yml

Change the site_name variable from:

site_name: My Docs

To:

site_name: Knowledge Base

You will see that change reflected in both of these spots:

![[Pasted image 20250531151848.png]]

[!NOTE] Note The site_name configuration option is the only required option in your configuration file.

Edit that .yml file again and add this line to apply this theme:

site_name: Knowledge Base  
theme:    
 name: mkdocs  
 color_mode: auto  
 user_color_mode_toggle: true

Additional theme options can be found here: https://www.mkdocs.org/user-guide/choosing-your-theme/

Create an About page:

nano ~/knowledge-base/my-project/docs/about.md

Paste this in (edit however you like):

# About

Welcome to my knowledge base.

## Purpose

This site documents various topics of interest, including:

- Linux tips
- Configuration guides
- Shell tricks
- Notes for future reference

## Credits

Created and maintained by Me.

Once you're happy with how it looks and you're ready to deploy to the web, run this command:

mkdocs build

That creates a new directory named site in ~/knowledge-base/my-project/:

admans@zserver:~/knowledge-base/my-project$ ls site/

404.html  about  css  img  index.html  js  Linux  search  sitemap.xml  sitemap.xml.gz  webfonts

At this point, you can deactivate your venv with this command:

deactivate

Make a new directory for your site and copy the contents of the site directory to it:

sudo mkdir -p /var/www/docs.bitwyre.cc

sudo cp -r ~/knowledge-base/my-project/site/* /var/www/docs.bitwyre.cc/

Create a new Nginx server block:

sudo nano /etc/nginx/sites-available/docs.bitwyre.cc

You can't just copy and paste this next part unless you're me because the way I have it set up is to enforce HTTPS which requires that you have an origin certificate and key in place in /etc/ssl/certs/ and /etc/ssl/private respectively. It's free to do. I generated mine from Cloudflare (free) since that's where this domain is pointing to for now, but you can also generate it for free from Let's Encrypt. If I don't have a guide on this site for doing this yet, you should ask ChatGPT or otherwise search the internet for a guide. Also, you would need to replace the domain names with your own:

server {  
   listen 80;  
   server_name docs.bitwyre.cc www.docs.bitwyre.cc;  

   root /var/www/docs.bitwyre.cc;  
   index index.html;  

   # Redirect HTTP to HTTPS  
   return 301 https://$host$request_uri;  
}  

server {  
   listen 443 ssl;  
   server_name docs.bitwyre.cc www.docs.bitwyre.cc;  

   root /var/www/docs.bitwyre.cc;  
   index index.html;  

   ssl_certificate /etc/ssl/certs/bitwyre.cc.pem;  
   ssl_certificate_key /etc/ssl/private/bitwyre.cc.key;  

   # Standard and secure ciphers  
   ssl_protocols TLSv1.2 TLSv1.3;  
   ssl_ciphers 'TLSv1.2:TLSv1.3:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!RC4:!MD5:!PSK';  
   ssl_prefer_server_ciphers on;  

   location / {  
       try_files $uri $uri/ =404;  
   }  
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/docs.bitwyre.cc /etc/nginx/sites-enabled/

Test and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

At this point, I could access the site at docs.bitwyre.cc

Non-venv Instructions (I'm not using these)

[!NOTE] Note Don't follow these instructions unless you have some reason you don't want to use the venv method. These instructions do work though.

[!NOTE] Note This assumes that you have already installed MkDocs. Also, I'm setting up MkDocs on an Ubuntu server that already has Nginx installed and running.

I will be hosting this on a subdomain called docs.bitwyre.cc.

To create a new project, run the following command from the command line:

mkdocs new my-project
cd my-project

This is what I actually ran:

mkdocs new knowledge-base
cd knowledge-base

The folder structure looks like this:

![[Pasted image 20250531144805.png]]

MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as mkdocs.yml and then run this command:

mkdocs serve

Navigate to http:127.0.0.1:8000 to see the site. I couldn't do this since I was on Ubuntu Server with no GUI. So, I pressed Ctrl + c to stop it and reran it like this to listen on all available network interfaces instead of just the localhost:

mkdocs serve --dev-addr=0.0.0.0:8000

Then, I could access it from another LAN machine's browser at: http://172.28.3.3:8000 . Replace the IP address with whatever your server's LAN address is. Make sure you're specifying http and not https.

Place any Markdown (.md) files you want to serve in the docs/ directory

By default, if you place loose .md file in there, they will appear as a new tab. For example, I put Installing TIDAL.md in the docs directory and now the site looks like this:

![[Pasted image 20250531150719.png]]

You can create additional directories in the docs directory if you want fewer tabs. For example, I put that .md file in a subdirectory called Linux and now it looks like this:

![[Pasted image 20250531150921.png]]

Next, to change the tab header from My Docs to whatever you like, edit this file:

sudo nano ~/knowledge-base/mkdocs.yml

Change the site_name variable from:

site_name: My Docs

To:

site_name: Knowledge Base

You will see that change reflected in both of these spots:

![[Pasted image 20250531151848.png]]

[!NOTE] Note The site_name configuration option is the only required option in your configuration file.

Edit that .yml file again and add this line to apply this theme:

site_name: Knowledge Base  
theme:    
 name: mkdocs  
 color_mode: auto  
 user_color_mode_toggle: true

Additional theme options can be found here: https://www.mkdocs.org/user-guide/choosing-your-theme/

Create an About page:

nano ~/knowledge-base/docs/about.md

Paste this in (edit however you like):

# About

Welcome to my knowledge base.

## Purpose

This site documents various topics of interest, including:

- Linux tips
- Configuration guides
- Shell tricks
- Notes for future reference

## Credits

Created and maintained by Me.

Once you're happy with how it looks and you're ready to deploy to the web, run this command:

mkdocs build

That creates a new directory named site in ~/knowledge-base/:

admans@zserver:~/knowledge-base$ ls site/

404.html  about  css  img  index.html  js  Linux  search  sitemap.xml  sitemap.xml.gz  webfonts

Make a new directory for your site and copy the contents of the site directory to it:

sudo mkdir -p /var/www/docs.bitwyre.cc

sudo cp -r ~/knowledge-base/site/* /var/www/docs.bitwyre.cc/

Create a new Nginx server block:

sudo nano /etc/nginx/sites-available/docs.bitwyre.cc

You can't just copy and paste this next part unless you're me because the way I have it set up is to enforce HTTPS which requires that you have an origin certificate and key in place in /etc/ssl/certs/ and /etc/ssl/private respectively. It's free to do. I generated mine from Cloudflare (free) since that's where this domain is pointing to for now, but you can also generate it for free from Let's Encrypt. If I don't have a guide on this site for doing this yet, you should ask ChatGPT or otherwise search the internet for a guide. Also, you would need to replace the domain names with your own:

server {  
   listen 80;  
   server_name docs.bitwyre.cc www.docs.bitwyre.cc;  

   root /var/www/docs.bitwyre.cc;  
   index index.html;  

   # Redirect HTTP to HTTPS  
   return 301 https://$host$request_uri;  
}  

server {  
   listen 443 ssl;  
   server_name docs.bitwyre.cc www.docs.bitwyre.cc;  

   root /var/www/docs.bitwyre.cc;  
   index index.html;  

   ssl_certificate /etc/ssl/certs/bitwyre.cc.pem;  
   ssl_certificate_key /etc/ssl/private/bitwyre.cc.key;  

   # Standard and secure ciphers  
   ssl_protocols TLSv1.2 TLSv1.3;  
   ssl_ciphers 'TLSv1.2:TLSv1.3:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!RC4:!MD5:!PSK';  
   ssl_prefer_server_ciphers on;  

   location / {  
       try_files $uri $uri/ =404;  
   }  
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/docs.bitwyre.cc /etc/nginx/sites-enabled/

Test and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

At this point, I could access the site at docs.bitwyre.cc

References