MajorLinux
84a1893e80
Corrected inflated article count (was 76, actual is 73). Updated domain breakdown and frontmatter timestamps from Obsidian. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
147 lines
4.1 KiB
Markdown
147 lines
4.1 KiB
Markdown
---
|
|
title: MajorWiki Setup & Publishing Pipeline
|
|
domain: troubleshooting
|
|
category: general
|
|
tags:
|
|
- mkdocs
|
|
- obsidian
|
|
- gitea
|
|
- docker
|
|
- self-hosting
|
|
status: published
|
|
created: 2026-03-11
|
|
updated: 2026-04-07T10:48
|
|
---
|
|
|
|
# MajorWiki Setup & Publishing Pipeline
|
|
|
|
A walkthrough of how MajorWiki is built, configured, and kept in sync — from writing in Obsidian to publishing via MkDocs.
|
|
|
|
## Architecture Overview
|
|
|
|
| Component | Role |
|
|
|-----------|------|
|
|
| Obsidian | Writing and editing markdown notes |
|
|
| Gitea | Self-hosted git remote at `git.majorshouse.com` |
|
|
| Webhook | Flask app on port 9091, triggers on push |
|
|
| MkDocs Material | Builds and serves the wiki at `notes.majorshouse.com` |
|
|
| Docker | Runs the MkDocs container (`majwiki`) |
|
|
|
|
## File Layout
|
|
|
|
```
|
|
/opt/majwiki/ # Git repo (content)
|
|
01-linux/
|
|
02-selfhosting/
|
|
04-streaming/
|
|
05-troubleshooting/
|
|
index.md
|
|
|
|
/opt/majwiki-config/ # Config files (outside git)
|
|
mkdocs.yml # docs_dir: docs
|
|
compose.yml # Docker Compose
|
|
webhook.py # Gitea webhook handler
|
|
```
|
|
|
|
## Publishing Flow
|
|
|
|
1. Write or edit a note in Obsidian
|
|
2. Obsidian syncs the vault to Gitea via git (using Obsidian Git plugin)
|
|
3. Gitea fires a POST to the webhook at port 9091
|
|
4. Webhook verifies the HMAC signature, runs `git pull` on `/opt/majwiki`
|
|
5. Webhook restarts the `majwiki` Docker container
|
|
6. MkDocs rebuilds the site and serves the updated content
|
|
|
|
## Key Configuration
|
|
|
|
### mkdocs.yml (in /opt/majwiki-config/)
|
|
|
|
The critical setting is `docs_dir: docs` — this tells MkDocs to look for
|
|
markdown files in the `docs/` subdirectory of its working directory, which
|
|
maps to `/opt/majwiki/` via the Docker volume mount.
|
|
|
|
### compose.yml volume mounts
|
|
|
|
```yaml
|
|
volumes:
|
|
- /opt/majwiki-config/mkdocs.yml:/docs/mkdocs.yml
|
|
- /opt/majwiki:/docs/docs
|
|
```
|
|
|
|
### Nav tabs require index.md files
|
|
|
|
Each section needs an `index.md` to make the top nav tabs clickable.
|
|
Without it, MkDocs renders the tab as a non-linked dropdown header.
|
|
These index files must live in the git repo root, not in any Obsidian
|
|
sync subfolder.
|
|
|
|
## Problems Encountered & Solutions
|
|
|
|
### index.md files not found by MkDocs
|
|
The git repo at `/opt/majwiki/` contains a `docs/` subdirectory used by
|
|
Obsidian sync. MkDocs was seeing index files at `docs/01-linux/index.md`
|
|
instead of `01-linux/index.md`. Fix: removed the stale copies from
|
|
`/opt/majwiki/docs/` and kept the authoritative ones in the repo root.
|
|
|
|
### mkdocs.yml wiped by git reset
|
|
Running `git reset --hard origin/main` on `/opt/majwiki/` deleted
|
|
`mkdocs.yml`, `compose.yml`, and `webhook.py` since they weren't tracked
|
|
in the repo. Fix: moved all config files to `/opt/majwiki-config/` outside
|
|
the git repo.
|
|
|
|
### docs_dir: . not allowed
|
|
MkDocs refuses `docs_dir: .` when `mkdocs.yml` is in the same directory.
|
|
Fix: mount `mkdocs.yml` separately at `/docs/mkdocs.yml` and the content
|
|
at `/docs/docs/` via Docker volumes, then set `docs_dir: docs`.
|
|
|
|
### Home page wikilinks not clickable
|
|
The original `index.md` used Obsidian-style `[[wikilinks]]` which MkDocs
|
|
renders as plain text. Fix: rewrote `index.md` using standard Markdown
|
|
links.
|
|
|
|
## Managing the Services
|
|
|
|
```bash
|
|
# Restart the wiki
|
|
cd /opt/majwiki-config && docker compose restart wiki
|
|
|
|
# Check webhook status
|
|
systemctl status majwiki-webhook
|
|
|
|
# View live logs
|
|
docker logs majwiki -f
|
|
|
|
# Force a manual pull
|
|
git -C /opt/majwiki pull --ff-only
|
|
```
|
|
|
|
## Webhook Service
|
|
|
|
The webhook runs as a systemd service so it survives reboots:
|
|
|
|
```
|
|
/etc/systemd/system/majwiki-webhook.service
|
|
```
|
|
|
|
```bash
|
|
systemctl status majwiki-webhook
|
|
systemctl restart majwiki-webhook
|
|
```
|
|
|
|
---
|
|
|
|
*Updated 2026-03-13: Obsidian Git plugin dropped. See canonical workflow below.*
|
|
|
|
## Canonical Publishing Workflow
|
|
|
|
The Obsidian Git plugin was evaluated but dropped — too convoluted for a simple push. Manual git from the terminal is the canonical workflow.
|
|
|
|
```bash
|
|
cd ~/Documents/MajorVault
|
|
git add 30-Areas/MajorWiki/
|
|
git commit -m "wiki: describe your changes"
|
|
git push
|
|
```
|
|
|
|
From there: Gitea receives the push → fires webhook → majorlab pulls → MkDocs rebuilds → `notes.majorshouse.com` updates.
|