Add projects/mkdocs_getting_started.md

projects/mkdocs_getting_started.md

@@ -0,0 +1,104 @@
+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
+```bash
+# 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
+```bash
+conda create -n mkdocs python=3.11 -y
+conda activate mkdocs
+```
+
+---
+
+### 3.  Install MkDocs + Material theme
+```bash
+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
+```bash
+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**:
+```bash
+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`:
+```ini
+[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:
+```bash
+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.