Deploying Your MkDocs Site on a Subdomain¶

This guide details how to deploy your MkDocs documentation to a subdomain (e.g., wiki.mus.is).

1. Build Your MkDocs Documentation¶

Navigate to your MkDocs project directory and build the static site:

mkdocs build

This creates the site/ directory with your generated documentation.

2. Set the DocumentRoot in Your Virtual Host¶

Ensure the Apache virtual host (configured in setup-subdomain.md) uses the correct path. For example, if your MkDocs project is in /var/www/wiki/, then the DocumentRoot should be:

DocumentRoot /var/www/wiki/site

Adjust the path if your project directory is different.

3. Adjust File Permissions¶

Make sure Apache can read your documentation files. For example:

sudo chown -R www-data:www-data /var/www/wiki/site

Alternatively, adjust permissions so that the Apache user has access.

4. Reload Apache to Apply Changes¶

sudo systemctl reload apache2

5. Verify Your Deployment¶

Open your browser and visit https://wiki.mus.is to ensure your MkDocs site is served correctly.

6. Troubleshooting¶

Permission Issues:
Confirm that the Apache user (www-data) has sufficient permissions to read your site/ directory.
Module Errors:
If you encounter errors like cannot find module 'pymdownx.emoji', install missing dependencies:
```
pip install mkdocs-material pymdown-extensions mkdocs-material-extensions
```
Refer to setup-mkdocs.md for further details.