From ed24ffdd647568cb7ba5b3607f3f1918f0eaef4a Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Wed, 4 Feb 2026 17:13:35 -0800 Subject: [PATCH] Enforce unique doc filenames and simple wiki-links Rename section index files to match their titles (tutorials.md, reference.md, how-to.md, explanation.md) so all filenames are unique. Convert all path-based wiki-links to simple filename format for better obsidian.nvim compatibility. Update doc-filenames task to no longer skip index.md files. Update doc-links task to reject path-based links containing '/'. Co-Authored-By: Claude Opus 4.5 --- docs/changelog.d/unique-doc-filenames.doc.md | 1 + docs/explanation/{index.md => explanation.md} | 0 docs/explanation/why-gitops.md | 6 +-- docs/how-to/add-ansible-role.md | 2 +- docs/how-to/{index.md => how-to.md} | 2 +- docs/index.md | 8 ++-- docs/reference/{index.md => reference.md} | 2 +- docs/reference/services/devpi.md | 2 +- docs/tutorials/ai-assistance-guide.md | 2 +- docs/tutorials/exploring-the-docs.md | 27 +++++++------ docs/tutorials/replicating-blumeops.md | 14 +++---- docs/tutorials/replication/argocd-config.md | 2 +- docs/tutorials/replication/core-services.md | 6 +-- .../replication/kubernetes-bootstrap.md | 2 +- .../replication/observability-stack.md | 2 +- docs/tutorials/replication/tailscale-setup.md | 4 +- docs/tutorials/{index.md => tutorials.md} | 10 ++--- mise-tasks/doc-filenames | 5 +-- mise-tasks/doc-links | 39 +++++++++++++++---- 19 files changed, 78 insertions(+), 58 deletions(-) create mode 100644 docs/changelog.d/unique-doc-filenames.doc.md rename docs/explanation/{index.md => explanation.md} (100%) rename docs/how-to/{index.md => how-to.md} (95%) rename docs/reference/{index.md => reference.md} (97%) rename docs/tutorials/{index.md => tutorials.md} (70%) diff --git a/docs/changelog.d/unique-doc-filenames.doc.md b/docs/changelog.d/unique-doc-filenames.doc.md new file mode 100644 index 0000000..9c24500 --- /dev/null +++ b/docs/changelog.d/unique-doc-filenames.doc.md @@ -0,0 +1 @@ +Enforce unique filenames and simple wiki-links across all documentation for better obsidian.nvim compatibility diff --git a/docs/explanation/index.md b/docs/explanation/explanation.md similarity index 100% rename from docs/explanation/index.md rename to docs/explanation/explanation.md diff --git a/docs/explanation/why-gitops.md b/docs/explanation/why-gitops.md index 6a98d24..126212c 100644 --- a/docs/explanation/why-gitops.md +++ b/docs/explanation/why-gitops.md @@ -44,8 +44,8 @@ BlumeOps uses layered GitOps: | Layer | Tool | What it manages | |-------|------|-----------------| -| **Tailnet** | [[reference/infrastructure/tailscale|Pulumi]] | ACLs, tags, DNS | -| **Host config** | [[reference/ansible/roles|Ansible]] | Services on [[indri]] | +| **Tailnet** | [[tailscale|Pulumi]] | ACLs, tags, DNS | +| **Host config** | [[roles|Ansible]] | Services on [[indri]] | | **Kubernetes** | [[argocd|ArgoCD]] | Containerized workloads | Each layer has its own reconciliation loop: @@ -67,4 +67,4 @@ But for BlumeOps, the trade-off is worth it. The infrastructure is complex enoug - [[architecture]] - How the pieces fit together - [[argocd]] - Kubernetes GitOps -- [[reference/ansible/roles|Ansible roles]] - Host configuration +- [[roles|Ansible roles]] - Host configuration diff --git a/docs/how-to/add-ansible-role.md b/docs/how-to/add-ansible-role.md index a8ab8d5..e30a562 100644 --- a/docs/how-to/add-ansible-role.md +++ b/docs/how-to/add-ansible-role.md @@ -136,6 +136,6 @@ See [[alloy]] for how metrics are collected from textfiles. ## Related -- [[reference/ansible/roles|Roles]] - Available roles reference +- [[roles|Roles]] - Available roles reference - [[indri]] - Target host - [[observability]] - Metrics collection diff --git a/docs/how-to/index.md b/docs/how-to/how-to.md similarity index 95% rename from docs/how-to/index.md rename to docs/how-to/how-to.md index a6fe23f..e4582c4 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/how-to.md @@ -6,7 +6,7 @@ tags: # How-To Guides -Task-oriented instructions for common BlumeOps operations. These guides assume you already understand the basic concepts - see [[tutorials/index|Tutorials]] if you're learning. +Task-oriented instructions for common BlumeOps operations. These guides assume you already understand the basic concepts - see [[tutorials|Tutorials]] if you're learning. ## Deployment diff --git a/docs/index.md b/docs/index.md index 2a2bec1..3fa7a3d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,8 +8,8 @@ Welcome to the BlumeOps documentation. ## Sections -- [[tutorials/index | Tutorials]] - Learning-oriented guides for getting started -- [[reference/index | Reference]] - Technical specifications and service details -- [[how-to/index | How-to]] - Task-oriented instructions for common operations -- [[explanation/index | Explanation]] - Understanding the "why" behind BlumeOps +- [[tutorials|Tutorials]] - Learning-oriented guides for getting started +- [[reference|Reference]] - Technical specifications and service details +- [[how-to|How-to]] - Task-oriented instructions for common operations +- [[explanation|Explanation]] - Understanding the "why" behind BlumeOps - [[CHANGELOG]] - Release history and changes diff --git a/docs/reference/index.md b/docs/reference/reference.md similarity index 97% rename from docs/reference/index.md rename to docs/reference/reference.md index c86d62e..7098101 100644 --- a/docs/reference/index.md +++ b/docs/reference/reference.md @@ -59,7 +59,7 @@ Cluster configuration and application registry. Configuration management for [[indri]]-hosted services. -- [[reference/ansible/roles | Roles]] - Available ansible roles +- [[roles]] - Available ansible roles ## Storage diff --git a/docs/reference/services/devpi.md b/docs/reference/services/devpi.md index 9c20c32..085666d 100644 --- a/docs/reference/services/devpi.md +++ b/docs/reference/services/devpi.md @@ -32,6 +32,6 @@ Root password stored in 1Password (blumeops vault), injected via ExternalSecret. ## Related -- [[how-to/use-pypi-proxy]] - Client configuration and package uploads +- [[use-pypi-proxy]] - Client configuration and package uploads - [[argocd]] - Deployment - [[1password]] - Secrets management diff --git a/docs/tutorials/ai-assistance-guide.md b/docs/tutorials/ai-assistance-guide.md index c553dec..9a707a8 100644 --- a/docs/tutorials/ai-assistance-guide.md +++ b/docs/tutorials/ai-assistance-guide.md @@ -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 diff --git a/docs/tutorials/exploring-the-docs.md b/docs/tutorials/exploring-the-docs.md index 1e356ec..8cf09e1 100644 --- a/docs/tutorials/exploring-the-docs.md +++ b/docs/tutorials/exploring-the-docs.md @@ -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. diff --git a/docs/tutorials/replicating-blumeops.md b/docs/tutorials/replicating-blumeops.md index 6ddb5c5..b58e425 100644 --- a/docs/tutorials/replicating-blumeops.md +++ b/docs/tutorials/replicating-blumeops.md @@ -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 diff --git a/docs/tutorials/replication/argocd-config.md b/docs/tutorials/replication/argocd-config.md index 2dcbe85..91e5637 100644 --- a/docs/tutorials/replication/argocd-config.md +++ b/docs/tutorials/replication/argocd-config.md @@ -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 diff --git a/docs/tutorials/replication/core-services.md b/docs/tutorials/replication/core-services.md index 100598e..85af3ac 100644 --- a/docs/tutorials/replication/core-services.md +++ b/docs/tutorials/replication/core-services.md @@ -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 diff --git a/docs/tutorials/replication/kubernetes-bootstrap.md b/docs/tutorials/replication/kubernetes-bootstrap.md index b92c025..7ffc9fa 100644 --- a/docs/tutorials/replication/kubernetes-bootstrap.md +++ b/docs/tutorials/replication/kubernetes-bootstrap.md @@ -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 diff --git a/docs/tutorials/replication/observability-stack.md b/docs/tutorials/replication/observability-stack.md index 4c3adb2..67c356c 100644 --- a/docs/tutorials/replication/observability-stack.md +++ b/docs/tutorials/replication/observability-stack.md @@ -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 diff --git a/docs/tutorials/replication/tailscale-setup.md b/docs/tutorials/replication/tailscale-setup.md index 23b9ea2..07a2217 100644 --- a/docs/tutorials/replication/tailscale-setup.md +++ b/docs/tutorials/replication/tailscale-setup.md @@ -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 diff --git a/docs/tutorials/index.md b/docs/tutorials/tutorials.md similarity index 70% rename from docs/tutorials/index.md rename to docs/tutorials/tutorials.md index 776e42b..013ccdf 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/tutorials.md @@ -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 | diff --git a/mise-tasks/doc-filenames b/mise-tasks/doc-filenames index 912effc..fe626f0 100755 --- a/mise-tasks/doc-filenames +++ b/mise-tasks/doc-filenames @@ -33,13 +33,10 @@ def main() -> int: # Key: filename (without .md), Value: list of file paths filenames: dict[str, list[str]] = defaultdict(list) - # Scan all markdown files (excluding zk/, changelog.d/, and index.md files) + # Scan all markdown files (excluding zk/ and changelog.d/) for md_file in sorted(DOCS_DIR.rglob("*.md")): if "changelog.d" in md_file.parts or "zk" in md_file.parts: continue - # Skip index.md files - they're expected to exist in multiple directories - if md_file.name == "index.md": - continue rel_path = str(md_file.relative_to(DOCS_DIR)) filename = md_file.stem # filename without .md diff --git a/mise-tasks/doc-links b/mise-tasks/doc-links index bdc0f2b..f34cc9b 100755 --- a/mise-tasks/doc-links +++ b/mise-tasks/doc-links @@ -8,12 +8,14 @@ This script scans all markdown files in the docs/ directory (excluding changelog.d/), extracts wiki-links, and verifies each link target -exists as a filename or path in the documentation. +exists as a unique filename in the documentation. Wiki-link formats supported: -- [[filename]] - links to filename.md (must be unique) -- [[path/to/file]] - links to path/to/file.md (for ambiguous filenames like index) -- [[target | Display Text]] - either format with display text +- [[filename]] - links to filename.md (must be unique across all docs) +- [[target|Display Text]] - filename with display text + +Path-based links (containing '/') are NOT supported to ensure all +filenames are unique and links work correctly in obsidian.nvim. Usage: mise run doc-links """ @@ -90,9 +92,10 @@ def main() -> int: if (REPO_ROOT / filename).exists(): valid_targets.add(Path(filename).stem) - # Collect all broken and ambiguous links + # Collect all broken, ambiguous, and path-based links broken_links: list[tuple[str, int, str]] = [] ambiguous_links: list[tuple[str, int, str, list[str]]] = [] + path_links: list[tuple[str, int, str]] = [] # Scan all markdown files for wiki-links (excluding changelog.d/) for md_file in sorted(DOCS_DIR.rglob("*.md")): @@ -103,8 +106,11 @@ def main() -> int: links = extract_wikilinks(md_file) for target, line_num in links: - if target in ambiguous_filenames: - # Link uses an ambiguous filename - needs to use full path + if "/" in target: + # Path-based links are not allowed - use simple filenames only + path_links.append((rel_path, line_num, target)) + elif target in ambiguous_filenames: + # Link uses an ambiguous filename - needs to be renamed ambiguous_links.append((rel_path, line_num, target, filename_counts[target])) elif target not in valid_targets: broken_links.append((rel_path, line_num, target)) @@ -117,11 +123,28 @@ def main() -> int: has_errors = False + if path_links: + has_errors = True + console.print("[bold red]Path-Based Wiki-Links Found[/bold red]") + console.print("Wiki-links must use simple filenames only (no '/' paths).") + console.print("Rename files to be unique, then use [[filename]] format.") + console.print() + table = Table(show_header=True, header_style="bold") + table.add_column("File") + table.add_column("Line", justify="right") + table.add_column("Target") + + for file_path, line_num, target in path_links: + table.add_row(file_path, str(line_num), escape(f"[[{target}]]")) + + console.print(table) + console.print() + if ambiguous_links: has_errors = True console.print("[bold red]Ambiguous Wiki-Links Found[/bold red]") console.print("These links use filenames that exist in multiple locations.") - console.print("Use the full path instead (e.g., [[reference/index]] not [[index]]).") + console.print("Rename files to be unique across all documentation.") console.print() table = Table(show_header=True, header_style="bold") table.add_column("File")