homelab/.claude/skills/wiki-docs.md

Wiki Documentation Skill

Create and manage markdown documentation files that sync to Wiki.js.

Context

Repository Location: /mnt/media/wikijs-content/ Git Remote: git.fig.systems/eddie/wiki.git Wiki.js URL: https://wiki.fig.systems

This repository is synchronized with Wiki.js. Any markdown files created here will automatically appear in the wiki after a sync (typically within 5 minutes, or immediately if triggered manually).

Capabilities

1. Create Documentation Pages

   • Write markdown files with proper Wiki.js frontmatter
   • Organize content in directories (maps to wiki hierarchy)
   • Add tags and metadata

2. Git Operations

   • Commit changes with descriptive messages
   • Push to remote repository
   • Pull latest changes before writing

3. Frontmatter Format All wiki pages require this YAML frontmatter:

   ---
   title: Page Title
   description: Brief description of the page
   published: true
   date: 2026-03-15T00:00:00.000Z
   tags: tag1, tag2, tag3
   editor: markdown
   dateCreated: 2026-03-15T00:00:00.000Z
   ---
   

   Important: Tags must be comma-separated, not YAML array format!

Workflow

When creating wiki documentation:

1. Navigate to repo:

   cd /mnt/media/wikijs-content
   

2. Pull latest changes:

   git pull
   

3. Write markdown file:

   • Use clear, descriptive filenames (lowercase-with-dashes.md)
   • Include proper frontmatter
   • Use standard markdown formatting
   • Organize in subdirectories as needed (e.g., home/containers/services/service-name.md)

4. Scan for secrets with Gitleaks:

   # Install gitleaks if not already installed
   # On Ubuntu/Debian: apt install gitleaks
   # Or download from: https://github.com/gitleaks/gitleaks/releases
   
   # Scan staged files before commit
   gitleaks detect --source . --verbose --no-git
   
   # Or scan specific files
   gitleaks detect --source . --verbose --no-git --log-opts="<filename>"
   

   If secrets are found:

   • Remove them immediately - replace with environment variables or placeholders
   • Use patterns like ${SECRET_KEY}, YOUR_KEY_HERE, or TBD
   • Never commit actual passwords, API keys, tokens, or credentials
   • Check .gitleaks.toml for allowlist patterns

5. Commit and push:

   git add <filename>
   git commit -m "Add/Update: brief description"
   git push
   

   Note: Gitleaks CI/CD will automatically scan on push and fail if secrets detected

6. Verify: Changes will appear at https://wiki.fig.systems after sync

File Organization

Suggested directory structure:

/mnt/media/wikijs-content/
├── homelab/
│   ├── services/
│   │   └── service-name.md
│   ├── networking/
│   │   └── traefik-setup.md
│   └── guides/
│       └── how-to-guide.md
├── development/
│   └── project-docs.md
└── reference/
    └── commands.md

Directories in the repo map to page hierarchy in Wiki.js.

Examples

Create a Service Documentation Page

---
title: Jellyfin Media Server
description: Jellyfin configuration and usage guide
published: true
date: 2026-03-15T00:00:00.000Z
tags: homelab, media, jellyfin
editor: markdown
dateCreated: 2026-03-15T00:00:00.000Z
---

# Jellyfin Media Server

Jellyfin is a free software media system...

## Access
- **URL:** https://jellyfin.fig.systems
- **Authentication:** Authelia SSO

## Configuration
...

Create a How-To Guide

---
title: How to Add a New Service
description: Step-by-step guide for adding services to the homelab
published: true
date: 2026-03-15T00:00:00.000Z
tags: homelab, guide, docker
editor: markdown
dateCreated: 2026-03-15T00:00:00.000Z
---

# How to Add a New Service

This guide walks through the process...

Git Configuration

The repository is already configured:

• User: Claude
• Email: claude@fig.systems
• Authentication: Token-based (embedded in remote URL)

Best Practices

1. Always pull before writing to avoid conflicts
2. Scan for secrets with Gitleaks before committing
3. Use descriptive commit messages following the pattern: "Add: X" or "Update: Y"
4. Include proper frontmatter - pages without it won't render correctly
5. Use semantic filenames - lowercase with dashes instead of spaces
6. Organize logically - use subdirectories for categories
7. Add relevant tags - helps with wiki navigation and search
8. Set published: true - pages with published: false won't be visible
9. Never commit secrets - use placeholders like TBD, ${VAR}, or YOUR_KEY_HERE

Secret Management with Gitleaks

What is Gitleaks?

Gitleaks is a secret scanner that detects hardcoded secrets, passwords, API keys, and tokens in Git repositories.

CI/CD Integration

The wiki repository has automated Gitleaks scanning:

• Workflow: .forgejo/workflows/gitleaks.yaml
• Config: .gitleaks.toml
• Triggers: Every push to main, all pull requests
• Action: Fails build if secrets detected

Local Scanning

Before committing:

cd /mnt/media/wikijs-content

# Scan all files
gitleaks detect --source . --verbose --no-git

# Scan specific files
gitleaks detect --source . --verbose --no-git --log-opts="path/to/file.md"

# Scan uncommitted changes only
gitleaks protect --staged --verbose

Handling Detected Secrets

If Gitleaks finds secrets:

1. Immediate action:

   • DO NOT commit
   • Replace secret with placeholder
   • Use TBD, ${SECRET_KEY}, or YOUR_KEY_HERE

2. Examples of safe placeholders:

   API_KEY=YOUR_API_KEY_HERE
   PASSWORD=${DB_PASSWORD}
   TOKEN=TBD
   

3. Allowlisted patterns (in .gitleaks.toml):

   • example.com domains
   • localhost and 127.0.0.1
   • TBD placeholders
   • Environment variable syntax ${VAR}

What Gitleaks Detects

• AWS keys (AKIA...)
• GitHub tokens (ghp_...)
• GitLab tokens (glpat-...)
• Private keys (-----BEGIN PRIVATE KEY-----)
• Generic API keys and secrets
• Passwords in configuration files

False Positives

If Gitleaks flags safe content:

1. Update .gitleaks.toml allowlist:

   [allowlist]
     regexes = [
       '''safe-pattern-here''',
     ]
   

2. Commit the config update:

   git add .gitleaks.toml
   git commit -m "chore: Update Gitleaks allowlist"
   

Git History Scanning

To scan entire git history:

gitleaks detect --source . --verbose

This checks all commits, not just current files.

Troubleshooting

If page doesn't appear in Wiki.js:

• Check Wiki.js logs: docker compose logs wikijs
• Manually trigger sync in Wiki.js admin panel (Storage section)
• Verify frontmatter is valid YAML
• Ensure file has .md extension

If git push fails:

• Check authentication token is still valid
• Verify network connectivity to git.fig.systems
• Try pulling first to resolve conflicts

If Gitleaks CI/CD fails:

• View Forgejo Actions logs at https://git.fig.systems/eddie/wiki/actions
• Identify detected secrets in the workflow output
• Remove or replace secrets with placeholders
• Update .gitleaks.toml if false positive
• Commit and push again

If Gitleaks not installed locally:

# Ubuntu/Debian
sudo apt install gitleaks

# Or download latest release
wget https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_linux_amd64.tar.gz
tar -xzf gitleaks_linux_amd64.tar.gz
sudo mv gitleaks /usr/local/bin/

Integration with Other Services

This wiki can document:

• Homelab services (compose/services/*)
• Infrastructure setup (Traefik, Authelia, LLDAP)
• Media management (*arr stack, Jellyfin)
• Development projects
• Personal notes and references

All documentation is version-controlled and backed up via Git!