Switch to title-based wiki-links (#91)
## Summary - Remove aliases from all zk cards to prevent them from capturing wiki-links - Convert all wiki-links from `[[filename|Title]]` to `[[Title]]` format - Replace `doc-filenames` task with `doc-titles` for duplicate title detection - Update pre-commit hook to use `doc-titles` Wiki-links now resolve to reference docs by their frontmatter title, which is more readable and maintainable than filename-based links. ## Deployment and Testing - [x] Pre-commit hooks pass (including new `doc-titles` check) - [x] Manually verified zk cards have aliases removed - [ ] Deploy docs v1.0.7 and verify wiki-links resolve correctly - [ ] Test links to reference docs (e.g., [[Grafana Alloy]], [[ArgoCD]]) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/91
This commit is contained in:
parent
6162179ac9
commit
01adc4cf0f
56 changed files with 501 additions and 431 deletions
|
|
@ -1,162 +0,0 @@
|
|||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# requires-python = ">=3.12"
|
||||
# dependencies = ["pyyaml>=6.0", "rich>=13.0.0"]
|
||||
# ///
|
||||
#MISE description="List all doc card filenames and detect duplicates"
|
||||
"""List all documentation card filenames and detect duplicates.
|
||||
|
||||
This script scans all markdown files in the docs/ directory (excluding
|
||||
changelog.d/), and reports any duplicate filenames that could cause
|
||||
wiki-link resolution issues with Quartz's "shortest" path mode.
|
||||
|
||||
With shortest mode, [[filename]] resolves to the file with that name,
|
||||
so filenames must be unique across the entire docs directory.
|
||||
|
||||
Usage: mise run doc-card-titles
|
||||
"""
|
||||
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
from rich.console import Console
|
||||
from rich.table import Table
|
||||
|
||||
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
||||
|
||||
|
||||
def extract_frontmatter(file_path: Path) -> dict | None:
|
||||
"""Extract YAML frontmatter from a markdown file."""
|
||||
content = file_path.read_text()
|
||||
if not content.startswith("---"):
|
||||
return None
|
||||
|
||||
# Find the closing ---
|
||||
end_idx = content.find("---", 3)
|
||||
if end_idx == -1:
|
||||
return None
|
||||
|
||||
frontmatter_text = content[3:end_idx].strip()
|
||||
try:
|
||||
return yaml.safe_load(frontmatter_text) or {}
|
||||
except yaml.YAMLError:
|
||||
return None
|
||||
|
||||
|
||||
def main() -> int:
|
||||
console = Console()
|
||||
|
||||
# Collect all filenames (without extension) and their full paths
|
||||
# Key: filename (stem), Value: list of full relative paths
|
||||
filenames: dict[str, list[str]] = defaultdict(list)
|
||||
|
||||
# Also collect id/aliases from zk cards for reference
|
||||
zk_identifiers: dict[str, list[tuple[str, str]]] = defaultdict(list)
|
||||
|
||||
# Scan all markdown files
|
||||
for md_file in sorted(DOCS_DIR.rglob("*.md")):
|
||||
# Skip changelog fragments
|
||||
if "changelog.d" in md_file.parts:
|
||||
continue
|
||||
|
||||
rel_path = str(md_file.relative_to(DOCS_DIR))
|
||||
filename = md_file.stem # filename without .md extension
|
||||
|
||||
filenames[filename].append(rel_path)
|
||||
|
||||
# For zk cards, also track id and aliases
|
||||
if "zk" in md_file.parts:
|
||||
frontmatter = extract_frontmatter(md_file)
|
||||
if frontmatter:
|
||||
card_id = frontmatter.get("id")
|
||||
if card_id:
|
||||
zk_identifiers[card_id].append((rel_path, "id"))
|
||||
aliases = frontmatter.get("aliases", [])
|
||||
for alias in aliases:
|
||||
zk_identifiers[alias].append((rel_path, "alias"))
|
||||
|
||||
# Find duplicate filenames (excluding "index" which is expected in multiple dirs)
|
||||
duplicates = {
|
||||
name: paths
|
||||
for name, paths in filenames.items()
|
||||
if len(paths) > 1 and name != "index"
|
||||
}
|
||||
|
||||
# Print results
|
||||
console.print("[bold]Doc Card Filename Inventory[/bold]")
|
||||
console.print()
|
||||
console.print("With Quartz 'shortest' path mode, wiki-links like [[filename]]")
|
||||
console.print("resolve by filename, so filenames must be unique.")
|
||||
console.print()
|
||||
|
||||
# Duplicates table (if any)
|
||||
if duplicates:
|
||||
console.print("[bold red]Duplicate Filenames Found[/bold red]")
|
||||
dup_table = Table(show_header=True, header_style="bold")
|
||||
dup_table.add_column("Filename")
|
||||
dup_table.add_column("Paths")
|
||||
|
||||
for filename in sorted(duplicates.keys()):
|
||||
paths = duplicates[filename]
|
||||
dup_table.add_row(filename, "\n".join(paths))
|
||||
|
||||
console.print(dup_table)
|
||||
console.print()
|
||||
|
||||
# All filenames table
|
||||
console.print("[bold]All Filenames[/bold]")
|
||||
all_table = Table(show_header=True, header_style="bold")
|
||||
all_table.add_column("Filename")
|
||||
all_table.add_column("Path")
|
||||
all_table.add_column("Status")
|
||||
|
||||
for filename in sorted(filenames.keys()):
|
||||
paths = filenames[filename]
|
||||
is_dup = filename in duplicates
|
||||
status = "[red]DUPLICATE[/red]" if is_dup else "[green]OK[/green]"
|
||||
all_table.add_row(filename, paths[0], status)
|
||||
for extra_path in paths[1:]:
|
||||
all_table.add_row("", extra_path, "")
|
||||
|
||||
console.print(all_table)
|
||||
|
||||
# ZK identifiers (for reference)
|
||||
if zk_identifiers:
|
||||
console.print()
|
||||
console.print("[bold]ZK Card Identifiers (id/aliases)[/bold]")
|
||||
zk_table = Table(show_header=True, header_style="bold")
|
||||
zk_table.add_column("Identifier")
|
||||
zk_table.add_column("Type")
|
||||
zk_table.add_column("File")
|
||||
|
||||
for identifier in sorted(zk_identifiers.keys()):
|
||||
sources = zk_identifiers[identifier]
|
||||
first = True
|
||||
for file_path, id_type in sources:
|
||||
zk_table.add_row(
|
||||
identifier if first else "",
|
||||
id_type,
|
||||
file_path,
|
||||
)
|
||||
first = False
|
||||
|
||||
console.print(zk_table)
|
||||
|
||||
# Summary
|
||||
console.print()
|
||||
console.print(f"Total files: {sum(len(p) for p in filenames.values())}")
|
||||
console.print(f"Unique filenames: {len(filenames)}")
|
||||
console.print(f"Duplicate filenames: {len(duplicates)}")
|
||||
|
||||
if duplicates:
|
||||
console.print()
|
||||
console.print("[bold red]Action required:[/bold red] Rename files to ensure unique filenames for wiki-link resolution.")
|
||||
return 1
|
||||
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
133
mise-tasks/doc-links
Executable file
133
mise-tasks/doc-links
Executable file
|
|
@ -0,0 +1,133 @@
|
|||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# requires-python = ">=3.12"
|
||||
# dependencies = ["pyyaml>=6.0", "rich>=13.0.0"]
|
||||
# ///
|
||||
#MISE description="Validate all wiki-links point to existing doc titles"
|
||||
"""Validate that all wiki-links in documentation point to existing titles.
|
||||
|
||||
This script scans all markdown files in the docs/ directory (excluding
|
||||
changelog.d/ and zk/), extracts wiki-links, and verifies each link target
|
||||
exists as a frontmatter title in the documentation.
|
||||
|
||||
Wiki-link formats supported:
|
||||
- [[Title]] - links to a doc with frontmatter title "Title"
|
||||
- [[Title|Display Text]] - links to "Title", displays "Display Text"
|
||||
|
||||
Usage: mise run doc-links
|
||||
"""
|
||||
|
||||
import re
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
from rich.console import Console
|
||||
from rich.markup import escape
|
||||
from rich.table import Table
|
||||
|
||||
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
||||
|
||||
# Regex to match wiki-links: [[Target]] or [[Target|Display]]
|
||||
WIKILINK_PATTERN = re.compile(r"\[\[([^\]|]+)(?:\|[^\]]+)?\]\]")
|
||||
|
||||
# Regex to match inline code (backticks)
|
||||
INLINE_CODE_PATTERN = re.compile(r"`[^`]+`")
|
||||
|
||||
|
||||
def extract_frontmatter(file_path: Path) -> dict | None:
|
||||
"""Extract YAML frontmatter from a markdown file."""
|
||||
content = file_path.read_text()
|
||||
if not content.startswith("---"):
|
||||
return None
|
||||
|
||||
end_idx = content.find("---", 3)
|
||||
if end_idx == -1:
|
||||
return None
|
||||
|
||||
frontmatter_text = content[3:end_idx].strip()
|
||||
try:
|
||||
return yaml.safe_load(frontmatter_text) or {}
|
||||
except yaml.YAMLError:
|
||||
return None
|
||||
|
||||
|
||||
def extract_wikilinks(file_path: Path) -> list[tuple[str, int]]:
|
||||
"""Extract all wiki-link targets from a markdown file with line numbers.
|
||||
|
||||
Ignores wiki-links inside inline code (backticks) as these are examples.
|
||||
"""
|
||||
content = file_path.read_text()
|
||||
links = []
|
||||
|
||||
for line_num, line in enumerate(content.splitlines(), start=1):
|
||||
# Remove inline code before searching for wiki-links
|
||||
line_without_code = INLINE_CODE_PATTERN.sub("", line)
|
||||
for match in WIKILINK_PATTERN.finditer(line_without_code):
|
||||
target = match.group(1).strip()
|
||||
links.append((target, line_num))
|
||||
|
||||
return links
|
||||
|
||||
|
||||
def main() -> int:
|
||||
console = Console()
|
||||
|
||||
# Collect all valid titles from frontmatter
|
||||
valid_titles: set[str] = set()
|
||||
|
||||
# Scan all markdown files for titles (excluding zk/ and changelog.d/)
|
||||
for md_file in DOCS_DIR.rglob("*.md"):
|
||||
if "changelog.d" in md_file.parts or "zk" in md_file.parts:
|
||||
continue
|
||||
|
||||
frontmatter = extract_frontmatter(md_file)
|
||||
if frontmatter and frontmatter.get("title"):
|
||||
valid_titles.add(frontmatter["title"])
|
||||
|
||||
# Collect all broken links
|
||||
# Key: (file_path, line_num), Value: target
|
||||
broken_links: list[tuple[str, int, str]] = []
|
||||
|
||||
# Scan all markdown files for wiki-links (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
|
||||
|
||||
rel_path = str(md_file.relative_to(DOCS_DIR))
|
||||
links = extract_wikilinks(md_file)
|
||||
|
||||
for target, line_num in links:
|
||||
if target not in valid_titles:
|
||||
broken_links.append((rel_path, line_num, target))
|
||||
|
||||
# Print results
|
||||
console.print("[bold]Wiki-Link Validation[/bold]")
|
||||
console.print()
|
||||
console.print(f"Found {len(valid_titles)} valid titles in documentation.")
|
||||
console.print()
|
||||
|
||||
if broken_links:
|
||||
console.print("[bold red]Broken Wiki-Links Found[/bold red]")
|
||||
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 broken_links:
|
||||
table.add_row(file_path, str(line_num), escape(f"[[{target}]]"))
|
||||
|
||||
console.print(table)
|
||||
console.print()
|
||||
console.print(f"[bold red]{len(broken_links)} broken link(s) found.[/bold red]")
|
||||
console.print()
|
||||
console.print("Each wiki-link target must match a frontmatter title in docs/.")
|
||||
return 1
|
||||
|
||||
console.print("[bold green]All wiki-links are valid![/bold green]")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
126
mise-tasks/doc-titles
Executable file
126
mise-tasks/doc-titles
Executable file
|
|
@ -0,0 +1,126 @@
|
|||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# requires-python = ">=3.12"
|
||||
# dependencies = ["pyyaml>=6.0", "rich>=13.0.0"]
|
||||
# ///
|
||||
#MISE description="List all doc card titles and detect duplicates"
|
||||
"""List all documentation card titles and detect duplicates.
|
||||
|
||||
This script scans all markdown files in the docs/ directory (excluding
|
||||
changelog.d/ and zk/), extracts frontmatter titles, and reports any
|
||||
duplicates that could cause wiki-link resolution issues.
|
||||
|
||||
With Quartz, wiki-links like [[Title]] resolve by frontmatter title,
|
||||
so titles must be unique across the documentation.
|
||||
|
||||
Usage: mise run doc-titles
|
||||
"""
|
||||
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
from rich.console import Console
|
||||
from rich.table import Table
|
||||
|
||||
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
||||
|
||||
|
||||
def extract_frontmatter(file_path: Path) -> dict | None:
|
||||
"""Extract YAML frontmatter from a markdown file."""
|
||||
content = file_path.read_text()
|
||||
if not content.startswith("---"):
|
||||
return None
|
||||
|
||||
end_idx = content.find("---", 3)
|
||||
if end_idx == -1:
|
||||
return None
|
||||
|
||||
frontmatter_text = content[3:end_idx].strip()
|
||||
try:
|
||||
return yaml.safe_load(frontmatter_text) or {}
|
||||
except yaml.YAMLError:
|
||||
return None
|
||||
|
||||
|
||||
def main() -> int:
|
||||
console = Console()
|
||||
|
||||
# Collect all titles and their source files
|
||||
# Key: title, Value: list of file paths
|
||||
titles: dict[str, list[str]] = defaultdict(list)
|
||||
|
||||
# Scan all markdown files (excluding zk/ and changelog.d/)
|
||||
for md_file in sorted(DOCS_DIR.rglob("*.md")):
|
||||
# Skip changelog fragments and zk cards
|
||||
if "changelog.d" in md_file.parts or "zk" in md_file.parts:
|
||||
continue
|
||||
|
||||
rel_path = str(md_file.relative_to(DOCS_DIR))
|
||||
frontmatter = extract_frontmatter(md_file)
|
||||
|
||||
if not frontmatter:
|
||||
continue
|
||||
|
||||
title = frontmatter.get("title")
|
||||
if title:
|
||||
titles[title].append(rel_path)
|
||||
|
||||
# Find duplicates
|
||||
duplicates = {title: paths for title, paths in titles.items() if len(paths) > 1}
|
||||
|
||||
# Print results
|
||||
console.print("[bold]Doc Card Title Inventory[/bold]")
|
||||
console.print()
|
||||
console.print("With Quartz, wiki-links like [[Title]] resolve by frontmatter title,")
|
||||
console.print("so titles must be unique across the documentation.")
|
||||
console.print()
|
||||
|
||||
# Duplicates table (if any)
|
||||
if duplicates:
|
||||
console.print("[bold red]Duplicate Titles Found[/bold red]")
|
||||
dup_table = Table(show_header=True, header_style="bold")
|
||||
dup_table.add_column("Title")
|
||||
dup_table.add_column("Files")
|
||||
|
||||
for title in sorted(duplicates.keys()):
|
||||
paths = duplicates[title]
|
||||
dup_table.add_row(title, "\n".join(paths))
|
||||
|
||||
console.print(dup_table)
|
||||
console.print()
|
||||
|
||||
# All titles table
|
||||
console.print("[bold]All Titles[/bold]")
|
||||
all_table = Table(show_header=True, header_style="bold")
|
||||
all_table.add_column("Title")
|
||||
all_table.add_column("File")
|
||||
all_table.add_column("Status")
|
||||
|
||||
for title in sorted(titles.keys()):
|
||||
paths = titles[title]
|
||||
is_dup = title in duplicates
|
||||
status = "[red]DUPLICATE[/red]" if is_dup else "[green]OK[/green]"
|
||||
all_table.add_row(title, paths[0], status)
|
||||
for extra_path in paths[1:]:
|
||||
all_table.add_row("", extra_path, "")
|
||||
|
||||
console.print(all_table)
|
||||
|
||||
# Summary
|
||||
console.print()
|
||||
console.print(f"Total files: {sum(len(p) for p in titles.values())}")
|
||||
console.print(f"Unique titles: {len(titles)}")
|
||||
console.print(f"Duplicate titles: {len(duplicates)}")
|
||||
|
||||
if duplicates:
|
||||
console.print()
|
||||
console.print("[bold red]Action required:[/bold red] Rename titles to ensure unique wiki-link resolution.")
|
||||
return 1
|
||||
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Loading…
Add table
Add a link
Reference in a new issue