---
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.