the_information_nexus/projects/mkdocs_getting_started.md

Bullet-proof recipe: MkDocs on a remote Linux host, served from Miniconda, reachable from your browser at http://YOUR_HOST_IP:8000.

---

1. SSH into your server & install Miniconda

# download latest installer
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
chmod +x Miniconda3-latest-Linux-x86_64.sh
./Miniconda3-latest-Linux-x86_64.sh   # say “yes” to auto-init 
exec $SHELL                           # reload shell

---

2. Create & activate an isolated environment

conda create -n mkdocs python=3.11 -y
conda activate mkdocs

---

3. Install MkDocs + Material theme

pip install mkdocs mkdocs-material

---

4. Drop your configuration.yml in place

Assume you already have a file called configuration.yml that contains everything (MkDocs will accept any name as long as you point to it).

Example directory layout (adjust to taste):

~/notes/
├── configuration.yml        # your ready-made config
└── docs/
    ├── index.md
    └── ...

---

5. One-liner to expose the docs publicly

cd ~/notes
mkdocs serve \
  --config-file configuration.yml \
  --dev-addr 0.0.0.0:8000 \
  --no-livereload           # optional: drops websocket, lighter

What this does

• --dev-addr 0.0.0.0:8000 listens on all interfaces, so the service is reachable at http://HOST_IP:8000 .
• --config-file lets you keep the non-standard name configuration.yml.

---

6. Quick sanity check

From your local machine:

curl http://HOST_IP:8000

You should get the HTML of your landing page.

---

7. (Optional) systemd service so it restarts on reboot

Create /etc/systemd/system/mkdocs.service:

[Unit]
Description=MkDocs dev server
After=network.target

[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER/notes
ExecStart=/home/YOUR_USER/miniconda3/envs/mkdocs/bin/mkdocs serve \
          --config-file /home/YOUR_USER/notes/configuration.yml \
          --dev-addr 0.0.0.0:8000 --no-livereload
Restart=always

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable --now mkdocs

---

8. Firewall / cloud security group

Open TCP 8000 inbound (e.g. sudo ufw allow 8000/tcp or your cloud panel).

---

9. Browse & iterate

Visit http://HOST_IP:8000 from anywhere—every save in docs/ triggers an auto-reload (unless --no-livereload was used).

That’s it—drop more Markdown files in docs/, edit configuration.yml, and you’re live.