Obsidian Vault Restructure: Transforming Monolithic Documentation into a Wiki

Executive Summary

Transformed a single 1,550-line markdown file containing all homelab infrastructure documentation into a structured Obsidian vault with 31 cross-referenced files organized across 8 thematic folders. Implemented wiki-style linking, git version control, and secure backup strategies while maintaining complete content fidelity.

Key Results:

• 31 organized files replacing monolithic 1,550-line document
• 8-folder taxonomy for logical content grouping
• Wiki-style cross-linking with 150+ internal references
• Git repository with security-hardened .gitignore
• Zero sensitive data exposure risk

The Problem

Monolithic Documentation Challenges

The homelab infrastructure documentation had grown organically into a single unwieldy file:

Pain Points:

• 1,550 lines in a single markdown file
• 25+ H2 sections covering disparate topics
• Difficult navigation - required scrolling or text search
• No cross-referencing between related topics
• Mixed concerns - infrastructure, services, projects, changelogs all intermingled
• Poor scalability - adding content made the file increasingly difficult to maintain
• Version control blind spots - single-file commits obscured what actually changed

Content Scope:

• Network topology and IP assignments
• Docker service configurations (15+ services)
• Monitoring stack documentation (Prometheus, Grafana, Loki)
• Security hardening notes
• Project documentation (3 major projects)
• Changelog entries (10+ sessions)
• Reference material (commands, troubleshooting, environment files)

Requirements for Solution

1. Maintainability - Easy to update individual topics without affecting others
2. Discoverability - Quick access to specific information
3. Relationships - Clear connections between related concepts
4. Scalability - Structure should support future growth
5. Version Control - Granular tracking of documentation changes
6. Security - Sensitive credentials must be excluded from version control
7. Portability - Standard markdown format for tool independence

Solution Architecture

Folder Taxonomy Design

Designed an 8-folder structure based on information architecture principles:

HomeLab/
├── _Index.md                    # Landing page (hub)
├── Infrastructure/              # Foundation (network, deployment)
├── Services/                    # Applications (largest category)
│   └── Monitoring/              # Subcategory for related services
├── Security/                    # Security-specific documentation
├── Projects/                    # Major initiatives
├── Reference/                   # Quick-reference material
├── Roadmap/                     # Planning and future work
└── Changelog/                   # Historical session notes
    └── 2026-02/                 # Organized by year-month

Design Rationale:

• Infrastructure - Foundational elements (network, deployment pipeline, workstation)
• Services - Operational applications (15+ services, warranted subcategories)
• Security - Isolated for Security+ certification focus
• Projects - High-level initiatives with their own lifecycles
• Reference - Frequently accessed quick-reference material
• Roadmap - Forward-looking planning
• Changelog - Historical records organized chronologically

Wiki Linking Strategy

Implemented Obsidian’s [[Page-Name]] wiki-style linking:

Link Types:

1. Hierarchical - Parent to child relationships
2. Cross-referential - Related concepts across categories
3. Bidirectional - Automatic backlinks via Obsidian
4. Contextual - Links embedded in natural language

Example Link Patterns:

# In Services/Homepage-Dashboard.md
**IP:** [[Network-Topology|192.168.1.4:4000]]
**Stack:** [[GitOps-Workflow|homelab-ops/proxmox/homepage/]]

Related: [[Dockhand]], [[Pi-hole]], [[Grafana]]

Benefits:

• Click-through navigation between related pages
• Backlinks panel shows what references each page
• Graph view visualizes documentation relationships
• Broken links highlighted in red (dead reference detection)

Content Mapping Strategy

Mapped monolithic sections to new file locations:

Implementation

Phase 1: Structure Creation

Created folder hierarchy and landing page:

mkdir -p Infrastructure Services Services/Monitoring Security \
         Projects Reference Roadmap Changelog Changelog/2026-02

Landing Page Design:

• Quick Links table with all major categories
• Network topology table (frequently referenced)
• Running containers overview
• Related notes references

Phase 2: Content Extraction and File Creation

Process:

1. Read original monolithic file
2. Extract section content with context preservation
3. Create new file with appropriate header
4. Add wiki links to related pages
5. Add navigation breadcrumb ([[_Index|← Back to Index]])

Header Template:

# Page Title

[[_Index|← Back to Index]]

**IP:** [[Network-Topology|192.168.1.X]] | **Stack:** [[GitOps-Workflow|path]]

---

## Content sections...

---

## Related Pages
- [[Related-Page-1]]
- [[Related-Page-2]]

Phase 3: Wiki Linking Implementation

Added cross-references following these patterns:

Service Files → Infrastructure:

**IP:** [[Network-Topology|192.168.1.4:3000]]
**Stack:** [[GitOps-Workflow|homelab-ops/proxmox/dockhand/]]

Monitoring Stack → Individual Services:

- [[Prometheus]] - Time-series metrics database
- [[Grafana]] - Visualization and dashboards
- [[Alertmanager]] - Alert routing

Changelog → Services:

Successfully added [[Prometheus]] monitoring for [[NAS-Synology]] via SNMP.

Total Links Created: 150+ internal wiki links

Phase 4: Git Repository Setup

Security-First Approach:

Created comprehensive .gitignore:

# Sensitive Files - Credentials and Tokens
Wazuh Creds.md
Token Github.md
Token for Homarr ProxMox.md
Secrets/
**/*secret*.md
**/*password*.md
**/*cred*.md

# Working Notes and Drafts
Build Outs/
Config Files/

# Archive and Old Files
_Archive-*.md
Homelab and Portfolio Log.md

# Obsidian Configuration
.obsidian/

Repository Initialization:

git init
git branch -m main
git add .
git status  # Verified sensitive files excluded
git commit -m "Initial commit: Obsidian vault restructure"

GitHub Integration:

gh repo create homelab-docs --private \
  --description "Structured Obsidian vault for homelab infrastructure documentation" \
  --source=. --remote=origin

git push -u origin main

Result: Private repository with 35 tracked files, zero sensitive data exposure.

Phase 5: Memory System Integration

Updated Claude Code memory system to reference new structure:

Global Memory Update (~/.claude/CLAUDE.md):

<documentation>
    <doc path="/home/cib/Documents/HomeLab/HomeLab/_Index.md" type="obsidian_vault">
        Obsidian Vault - Structured homelab documentation with wiki-style linking.
        31 files across 8 folders: Infrastructure, Services, Security, Projects,
        Reference, Roadmap, Changelog.
    </doc>
    <vault_structure>
        Infrastructure/ - Network topology, GitOps workflow, workstation setup
        Services/ - Homepage, Dockhand, Pi-hole, Minecraft, NAS, Monitoring/
        Security/ - Wazuh SIEM, security hardening, best practices
        Projects/ - Podcast Studio, Portfolio Site, Claude Memory System
        Reference/ - Docker commands, troubleshooting, environment files
        Roadmap/ - Future plans, current TODO
        Changelog/ - Session notes organized by date
    </vault_structure>
</documentation>

Benefits:

• AI assistant knows vault structure
• Can reference specific pages in responses
• Understands relationships between pages
• Maintains wiki linking conventions

Results

Quantitative Metrics

Qualitative Improvements

Navigation:

• ✅ Click-through navigation via wiki links
• ✅ Breadcrumb trail (back to index)
• ✅ Automatic backlinks panel
• ✅ Graph view visualization

Maintainability:

• ✅ Update single page without affecting others
• ✅ Git commits show exact scope of change
• ✅ Easy to reorganize by moving files
• ✅ Add new pages without cluttering existing content

Discoverability:

• ✅ Topic-based file names (search for “prometheus” finds exact file)
• ✅ Related pages linked at bottom
• ✅ Backlinks show all references to a page
• ✅ Table of contents at _Index.md

Security:

• ✅ Credentials excluded via .gitignore
• ✅ Private GitHub repository
• ✅ No secrets in commit history
• ✅ Future-proofed with pattern matching

File Statistics

├── Infrastructure/ (3 files)
│   └── ~80 lines avg
├── Services/ (11 files)
│   └── ~120 lines avg
├── Security/ (3 files)
│   └── ~180 lines avg
├── Projects/ (3 files)
│   └── ~140 lines avg
├── Reference/ (5 files)
│   └── ~90 lines avg
├── Roadmap/ (2 files)
│   └── ~110 lines avg
└── Changelog/ (6 files)
    └── ~280 lines avg (detailed session notes)

Total: 3,898 lines across 35 files

Technical Challenges & Solutions

Challenge 1: Content Decomposition

Problem: How to split highly interconnected content without losing context?

Solution:

• Created _Index.md as aggregation point
• Added “Related Pages” sections to each file
• Used wiki links with context ([[Page|descriptive text]])
• Preserved original file as _Archive-Original-2026-02-04.md

Challenge 2: Link Maintenance

Problem: With 150+ links, how to avoid broken references?

Solution:

• Obsidian’s built-in link validation (shows broken links in red)
• Standardized page naming convention (Title-Case-With-Hyphens)
• Used descriptive link text for clarity
• Verified all links after restructure

Challenge 3: Sensitive Data Protection

Problem: Vault contained credentials mixed with documentation.

Solution:

• Comprehensive .gitignore with pattern matching
• Verified with git status before initial commit
• Private repository as additional safeguard
• Created separate Secrets/ folder (gitignored) for credentials

Challenge 4: Historical Context Preservation

Problem: Monolithic file had chronological changelog that showed evolution.

Solution:

• Created Changelog/ folder with detailed session notes
• Organized by year-month subfolders
• Each session gets dedicated file with full context
• _Changelog-Index.md provides timeline overview

Challenge 5: Memory System Integration

Problem: AI assistant’s memory pointed to old monolithic file.

Solution:

• Updated global memory with vault structure
• Added vault taxonomy to memory system
• Included example navigation patterns
• Synced to backup repository (ai-assistant-config)

Skills Demonstrated

Information Architecture

• Taxonomy Design - Created logical 8-folder structure based on content types and user needs
• Content Modeling - Mapped 25+ sections to appropriate categories
• Navigation Design - Implemented hub-and-spoke model with _Index.md as central hub
• Relationship Mapping - Identified and linked 150+ cross-references

Technical Writing

• Clarity - Each page has clear purpose and scope
• Consistency - Standardized headers, formatting, and link patterns
• Completeness - All original content preserved with added context
• Accessibility - Breadcrumb navigation and related pages for wayfinding

Version Control

• Git Workflow - Repository initialization, branching strategy (main)
• Security - Comprehensive .gitignore to exclude sensitive data
• Commit Hygiene - Descriptive commit messages with context
• Remote Management - GitHub CLI integration, private repository setup

Knowledge Management

• Wiki Methodology - Bidirectional linking, backlinks, graph visualization
• Metadata Management - Frontmatter for Obsidian features
• Search Optimization - File naming for quick discovery
• Scalability - Structure supports unlimited growth

Automation & Integration

• Memory System - Updated AI assistant memory with new structure
• Backup Strategy - Automated sync to backup repository
• Documentation as Code - Git-versioned markdown files
• Tool Integration - Obsidian + Git + GitHub + Claude Code

Lessons Learned

Documentation Debt is Real

Large monolithic files accumulate slowly. Restructuring took ~2 hours but saved future hours of inefficiency.

Early Structure Pays Off

Starting with good taxonomy prevents future reorganization. The 8-folder structure should scale to 100+ files.

Security by Default

Including comprehensive .gitignore from day one prevents credential leaks. Pattern matching catches future additions.

Tools Matter

Obsidian’s wiki links + graph view + backlinks made restructuring valuable. Standard markdown maintains portability.

Context Preservation

Keeping _Archive-Original-2026-02-04.md provides safety net. No information was lost during restructure.

Future Enhancements

Phase 2 Improvements

• Add frontmatter metadata (tags, categories, dates)
• Create custom Obsidian templates for new pages
• Implement automated link validation in CI/CD
• Add diagrams (network topology, architecture) using Mermaid
• Create Obsidian Dataview queries for dynamic indexes

Advanced Features

• Publish vault to static site (Obsidian Publish or custom)
• Add full-text search with Algolia or similar
• Implement automated changelog generation from git commits
• Create dashboard views for service status
• Add automated backups to multiple locations

Integration Opportunities

• Link to portfolio projects from vault
• Generate resume content from vault data
• Create automated documentation from infrastructure as code
• Implement bidirectional sync with homelab-ops repository

Conclusion

Restructuring 1,550 lines of monolithic documentation into a 31-file Obsidian vault with wiki-style linking transformed homelab documentation from a maintenance burden into a professional knowledge base. The git-versioned structure with comprehensive security measures provides both historical tracking and credential protection.

The project demonstrates proficiency in information architecture, technical writing, version control, and knowledge management - all critical skills for IT infrastructure roles. The scalable taxonomy and wiki methodology ensure the documentation will remain maintainable as the homelab grows.

Repository: https://github.com/jhathcock-sys/homelab-docs (Private)

Key Takeaway: Investing time in documentation structure pays compounding dividends in maintenance efficiency and knowledge transfer.

Project completed: February 4, 2026

Tools used: Obsidian, Git, GitHub CLI, Claude Code, Markdown