eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions

Enforce unique doc filenames and simple wiki-links (#109)

Browse source 
## Summary
- Rename section index files to match their titles (tutorials.md, reference.md, how-to.md, explanation.md) so all filenames are unique
- Convert all ~47 path-based wiki-links to simple filename format across 15 files
- Update doc-filenames task to no longer skip index.md files
- Update doc-links task to reject path-based links containing '/'

This ensures all wiki-links work correctly in obsidian.nvim by making links resolvable by filename alone.

## Testing
- `mise run doc-filenames` - all unique
- `mise run doc-links` - no broken or path-based links
- `mise run doc-titles` - no duplicates

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/109
This commit is contained in:
Erich Blume 2026-02-04 17:21:34 -08:00
commit 3da455e49c
45 changed files with 176 additions and 125 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/tutorials/adding-a-service.md
View file

@ -14,7 +14,7 @@ This tutorial walks through deploying a new service to BlumeOps via ArgoCD, incl
## Prerequisites
- Access to the [[tailscale | Tailscale]] network
- Access to the [[tailscale|Tailscale]] network
- `kubectl` configured with `minikube-indri` context
- `argocd` CLI installed (via Brewfile: `brew bundle`)

6
docs/tutorials/ai-assistance-guide.md
View file

@ -62,9 +62,9 @@ Types (file suffix): `.feature`, `.bugfix`, `.infra`, `.doc`, `.ai`, `.misc`
### Wiki-Link Formatting
Use simple wiki-links without alternate text or extra spaces:
- Prefer `[[borgmatic]]` over `[[borgmatic | Borgmatic]]`
- Prefer `[[borgmatic]]` over `[[borgmatic|Borgmatic]]`
- Only use alternate text when grammatically warranted (e.g., `[[cluster|Kubernetes]]` reads better than `[[cluster]]`)
- No spaces around the pipe: `[[path|Text]]` not `[[ path | Text ]]`
- No spaces around the pipe: `[[path|Text]]` not `[[ path|Text ]]`
When editing documentation, rewrite links to follow this convention as you encounter them.
@ -108,7 +108,7 @@ For ArgoCD operations, use the `argocd` CLI directly:
For AI agents building context:
- [[reference/index|Reference Index]] - Entry point for technical details
- [[reference|Reference]] - Entry point for technical details
- [[hosts|Host Inventory]] - What hardware exists
- [[apps|ArgoCD Apps]] - What's deployed in Kubernetes
- [[routing|Routing]] - How services are exposed

27
docs/tutorials/exploring-the-docs.md
View file

@ -17,18 +17,18 @@ The docs follow the [Diataxis](https://diataxis.fr/) framework:
| Section | Purpose | When to Use |
|---------|---------|-------------|
| **[[tutorials/index | Tutorials]]** | Learning-oriented | "I'm new and want to understand" |
| **[[reference/index | Reference]]** | Information-oriented | "I need specific technical details" |
| **[[how-to/index | How-to]]** | Task-oriented | "I need to do X" |
| **[[explanation/index | Explanation]]** | Understanding-oriented | "I want to understand why" |
| **[[tutorials|Tutorials]]** | Learning-oriented | "I'm new and want to understand" |
| **[[reference|Reference]]** | Information-oriented | "I need specific technical details" |
| **[[how-to|How-to]]** | Task-oriented | "I need to do X" |
| **[[explanation|Explanation]]** | Understanding-oriented | "I want to understand why" |
## Quick Paths by Audience
### For Erich (Owner)
You probably want quick access to operational details:
- [[how-to/index|How-to guides]] for common operations (deploy, troubleshoot, update ACLs)
- [[reference/index|Reference]] has service URLs, commands, and config locations
- [[how-to|How-to guides]] for common operations (deploy, troubleshoot, update ACLs)
- [[reference|Reference]] has service URLs, commands, and config locations
- [[ai-assistance-guide]] explains how to work effectively with Claude
- Run `mise run zk-docs` to prime AI context with key documentation
@ -36,29 +36,29 @@ You probably want quick access to operational details:
Context for effective assistance:
- Read [[ai-assistance-guide]] for operational conventions
- [[reference/index|Reference]] has the technical specifics you'll need
- [[reference|Reference]] has the technical specifics you'll need
- The repo's `CLAUDE.md` has critical rules (especially the kubectl context requirement)
### For External Readers
Understanding what this is:
- [[explanation/index|Explanation]] covers the "why" behind design decisions
- [[reference/index|Reference]] shows what's actually running
- [[explanation|Explanation]] covers the "why" behind design decisions
- [[reference|Reference]] shows what's actually running
- Browse service pages to see specific implementations
### For Contributors
Getting started with changes:
- [[contributing]] walks through the workflow
- [[how-to/index|How-to guides]] for specific tasks (deploy services, add roles)
- [[reference/index|Reference]] tells you where things live
- [[how-to|How-to guides]] for specific tasks (deploy services, add roles)
- [[reference|Reference]] tells you where things live
### For Replicators
Replicators are people who want to build their own similar homelab GitOps setup, using BlumeOps as inspiration.
- [[replicating-blumeops]] provides the overview
- [[explanation/index|Explanation]] covers architecture and design rationale
- [[explanation|Explanation]] covers architecture and design rationale
- The `replication/` tutorials go deep on components
- Reference pages show specific configuration choices
@ -66,8 +66,7 @@ Replicators are people who want to build their own similar homelab GitOps setup,
Documentation uses `[[wiki-links]]` for cross-references:
- `[[service-name]]` links to a reference page
- `[[folder/page]]` links to nested pages
- `[[page | Display Text]]` customizes the link text
- `[[page|Display Text]]` customizes the link text
When reading on the web (docs.ops.eblu.me), these render as clickable links. The backlinks panel shows what references each page.

14
docs/tutorials/replicating-blumeops.md
View file

@ -38,7 +38,7 @@ You can start with a single machine and add storage later.
Before deploying services, establish secure connectivity.
**[[tutorials/replication/tailscale-setup|Setting Up Tailscale]]**
**[[tailscale-setup|Setting Up Tailscale]]**
- Create a tailnet and connect your devices
- Configure ACLs for service access
- Set up MagicDNS for convenient naming
@ -49,7 +49,7 @@ This replaces: traditional VPNs, port forwarding, dynamic DNS
Bootstrap the essential services that everything else depends on.
**[[tutorials/replication/core-services | Core Services Setup]]**
**[[core-services|Core Services Setup]]**
- Set up [[forgejo]] for git hosting and CI/CD
- Optionally set up [[zot]] container registry
- Configure SSH access and deploy keys
@ -60,7 +60,7 @@ Forgejo is central to GitOps - it's where your infrastructure definitions live a
A cluster for running containerized workloads.
**[[tutorials/replication/kubernetes-bootstrap|Bootstrapping Kubernetes]]**
**[[kubernetes-bootstrap|Bootstrapping Kubernetes]]**
- Install minikube (or k3s, kind, etc.)
- Configure persistent storage
- Expose the API securely via Tailscale
@ -71,7 +71,7 @@ BlumeOps uses minikube for simplicity, but the patterns apply to any distributio
Declarative, git-driven deployments.
**[[tutorials/replication/argocd-config|Configuring ArgoCD]]**
**[[argocd-config|Configuring ArgoCD]]**
- Install ArgoCD in your cluster
- Connect to your git repository
- Deploy your first application
@ -83,7 +83,7 @@ This is the heart of GitOps - changes in git automatically sync to your cluster.
Know what's happening in your infrastructure.
**[[tutorials/replication/observability-stack|Building the Observability Stack]]**
**[[observability-stack|Building the Observability Stack]]**
- Deploy Prometheus for metrics
- Deploy Loki for logs
- Deploy Grafana for dashboards
@ -131,9 +131,9 @@ The principles (GitOps, IaC, observability) matter more than specific tools.
## Getting Started
Begin with [[tutorials/replication/tailscale-setup]] - networking is the foundation everything else builds on.
Begin with [[tailscale-setup]] - networking is the foundation everything else builds on.
## Related
- [[reference/index]] - See BlumeOps' specific configurations
- [[reference]] - See BlumeOps' specific configurations
- [[contributing]] - Help improve BlumeOps instead

2
docs/tutorials/replication/argocd-config.md
View file

@ -198,7 +198,7 @@ BlumeOps uses manual sync for workloads, auto sync only for the `apps` Applicati
## Next Steps
- [[tutorials/replication/observability-stack | Build observability]] - Monitor your deployments
- [[observability-stack|Build observability]] - Monitor your deployments
- Add more applications to your repo
- Set up notifications for sync failures

6
docs/tutorials/replication/core-services.md
View file

@ -10,7 +10,7 @@ tags:
> **Audiences:** Replicator
>
> **Prerequisites:** [[tutorials/replication/tailscale-setup | Tailscale Setup]]
> **Prerequisites:** [[tailscale-setup|Tailscale Setup]]
This tutorial walks through setting up the foundational services that your GitOps infrastructure depends on: a git forge and optionally a container registry.
@ -29,7 +29,7 @@ Forgejo runs directly on your server (not in Kubernetes) because Kubernetes depe
### Using Ansible (BlumeOps Approach)
BlumeOps manages Forgejo via an Ansible role. See [[reference/ansible/roles | Ansible Roles]].
BlumeOps manages Forgejo via an Ansible role. See [[roles|Ansible Roles]].
### Manual Installation
@ -101,7 +101,7 @@ For getting started, you can skip this and use public registries.
## Next Steps
- [[tutorials/replication/kubernetes-bootstrap | Bootstrap Kubernetes]] - Now that you have a git repo, set up your cluster
- [[kubernetes-bootstrap|Bootstrap Kubernetes]] - Now that you have a git repo, set up your cluster
- Configure Forgejo webhooks for ArgoCD (after ArgoCD is running)
## BlumeOps Specifics

2
docs/tutorials/replication/kubernetes-bootstrap.md
View file

@ -148,7 +148,7 @@ spec:
## Next Steps
- [[tutorials/replication/argocd-config | Configure ArgoCD]] - GitOps deployments
- [[argocd-config|Configure ArgoCD]] - GitOps deployments
- Install essential addons (ingress controller, cert-manager)
## BluemeOps Specifics

2
docs/tutorials/replication/observability-stack.md
View file

@ -177,7 +177,7 @@ spec:
namespace: monitoring
```
BluemeOps uses Alloy on both [[indri]] (for host metrics, via [[reference/ansible/roles | Ansible role]]) and in the [[cluster]] (for pod logs and service probes).
BluemeOps uses Alloy on both [[indri]] (for host metrics, via [[roles|Ansible role]]) and in the [[cluster]] (for pod logs and service probes).
## What You Now Have

4
docs/tutorials/replication/tailscale-setup.md
View file

@ -112,8 +112,8 @@ Tags must be defined in ACLs before use.
## Next Steps
With networking established:
- [[tutorials/replication/core-services | Set Up Core Services]] - Install Forgejo and optionally a container registry
- [[tutorials/replication/kubernetes-bootstrap | Bootstrap Kubernetes]] - Your cluster will join the tailnet
- [[core-services|Set Up Core Services]] - Install Forgejo and optionally a container registry
- [[kubernetes-bootstrap|Bootstrap Kubernetes]] - Your cluster will join the tailnet
## BlumeOps Specifics

10
docs/tutorials/index.md → docs/tutorials/tutorials.md
View file

@ -41,8 +41,8 @@ For those building their own homelab GitOps setup.
| Tutorial | Audiences | Description |
|----------|-----------|-------------|
| [[replicating-blumeops]] | Replicator | Overview: building a similar environment |
| [[tutorials/replication/tailscale-setup | Tailscale Setup]] | Replicator | Setting up Tailscale networking |
| [[tutorials/replication/core-services | Core Services]] | Replicator | Forgejo and container registry |
| [[tutorials/replication/kubernetes-bootstrap | Kubernetes Bootstrap]] | Replicator | Bootstrapping a Kubernetes cluster |
| [[tutorials/replication/argocd-config | ArgoCD Config]] | Replicator | Configuring GitOps with ArgoCD |
| [[tutorials/replication/observability-stack | Observability Stack]] | Replicator | Metrics, logs, and dashboards |
| [[tailscale-setup|Tailscale Setup]] | Replicator | Setting up Tailscale networking |
| [[core-services|Core Services]] | Replicator | Forgejo and container registry |
| [[kubernetes-bootstrap|Kubernetes Bootstrap]] | Replicator | Bootstrapping a Kubernetes cluster |
| [[argocd-config|ArgoCD Config]] | Replicator | Configuring GitOps with ArgoCD |
| [[observability-stack|Observability Stack]] | Replicator | Metrics, logs, and dashboards |