Switch to filename-based wiki-links (Quartz resolves by filename)
- Convert all wiki-links from title-based to filename-based - Update doc-links to validate against filenames - Add doc-filenames task for duplicate filename detection - Consolidate doc hooks into single local block in pre-commit config Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
d359583d0a
commit
9630655cc9
28 changed files with 166 additions and 149 deletions
88
mise-tasks/doc-filenames
Executable file
88
mise-tasks/doc-filenames
Executable file
|
|
@ -0,0 +1,88 @@
|
|||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# requires-python = ">=3.12"
|
||||
# dependencies = ["rich>=13.0.0"]
|
||||
# ///
|
||||
#MISE description="Detect duplicate filenames in documentation"
|
||||
"""Detect duplicate filenames in documentation.
|
||||
|
||||
This script scans all markdown files in the docs/ directory (excluding
|
||||
changelog.d/ and zk/) and reports any duplicate filenames that could
|
||||
cause wiki-link resolution issues.
|
||||
|
||||
With Quartz, wiki-links like [[filename]] resolve by filename,
|
||||
so filenames must be unique across the documentation.
|
||||
|
||||
Usage: mise run doc-filenames
|
||||
"""
|
||||
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
from pathlib import Path
|
||||
|
||||
from rich.console import Console
|
||||
from rich.table import Table
|
||||
|
||||
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
||||
|
||||
|
||||
def main() -> int:
|
||||
console = Console()
|
||||
|
||||
# Collect all filenames and their paths
|
||||
# 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)
|
||||
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
|
||||
filenames[filename].append(rel_path)
|
||||
|
||||
# Find duplicates
|
||||
duplicates = {name: paths for name, paths in filenames.items() if len(paths) > 1}
|
||||
|
||||
# Print results
|
||||
console.print("[bold]Doc Filename Inventory[/bold]")
|
||||
console.print()
|
||||
console.print("With Quartz, wiki-links like [[filename]] resolve by filename,")
|
||||
console.print("so filenames must be unique across the documentation.")
|
||||
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 name in sorted(duplicates.keys()):
|
||||
paths = duplicates[name]
|
||||
dup_table.add_row(name, "\n".join(paths))
|
||||
|
||||
console.print(dup_table)
|
||||
console.print()
|
||||
|
||||
# Summary
|
||||
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 wiki-link resolution.")
|
||||
return 1
|
||||
|
||||
console.print()
|
||||
console.print("[bold green]All filenames are unique![/bold green]")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
|
|
@ -1,29 +1,26 @@
|
|||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# requires-python = ">=3.12"
|
||||
# dependencies = ["pyyaml>=6.0", "rich>=13.0.0"]
|
||||
# dependencies = ["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.
|
||||
#MISE description="Validate all wiki-links point to existing doc filenames"
|
||||
"""Validate that all wiki-links in documentation point to existing filenames.
|
||||
|
||||
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.
|
||||
exists as a filename in the documentation.
|
||||
|
||||
Wiki-link formats supported:
|
||||
- [[target]] - links to a doc with frontmatter title "target"
|
||||
- [[target | Display Text]] - links to "target", displays "Display Text"
|
||||
(spaces around the pipe are REQUIRED)
|
||||
- [[filename]] - links to filename.md
|
||||
- [[filename | Display Text]] - links to filename.md, 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
|
||||
|
|
@ -31,32 +28,12 @@ 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"\[\[([^\]|]+)(?:\s+\|\s+[^\]]+)?\]\]")
|
||||
|
||||
# Regex to detect any wiki-link with a pipe (for format checking)
|
||||
WIKILINK_WITH_PIPE_PATTERN = re.compile(r"\[\[([^\]]+)\]\]")
|
||||
WIKILINK_PATTERN = re.compile(r"\[\[([^\]|]+)(?:\s*\|\s*[^\]]+)?\]\]")
|
||||
|
||||
# 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.
|
||||
|
||||
|
|
@ -75,41 +52,20 @@ def extract_wikilinks(file_path: Path) -> list[tuple[str, int]]:
|
|||
return links
|
||||
|
||||
|
||||
def find_unspaced_pipes(file_path: Path) -> list[tuple[str, int]]:
|
||||
"""Find wiki-links with unspaced pipes (e.g., [[target|display]] instead of [[target | display]])."""
|
||||
content = file_path.read_text()
|
||||
issues = []
|
||||
|
||||
for line_num, line in enumerate(content.splitlines(), start=1):
|
||||
# Remove inline code before searching
|
||||
line_without_code = INLINE_CODE_PATTERN.sub("", line)
|
||||
for match in WIKILINK_WITH_PIPE_PATTERN.finditer(line_without_code):
|
||||
inner = match.group(1)
|
||||
# Check if there's a pipe without proper spacing (space on both sides)
|
||||
if "|" in inner and " | " not in inner:
|
||||
issues.append((match.group(0), line_num))
|
||||
|
||||
return issues
|
||||
|
||||
|
||||
def main() -> int:
|
||||
console = Console()
|
||||
|
||||
# Collect all valid titles from frontmatter
|
||||
valid_titles: set[str] = set()
|
||||
# Collect all valid filenames
|
||||
valid_filenames: set[str] = set()
|
||||
|
||||
# Scan all markdown files for titles (excluding zk/ and changelog.d/)
|
||||
# Scan all markdown files for filenames (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
|
||||
valid_filenames.add(md_file.stem)
|
||||
|
||||
frontmatter = extract_frontmatter(md_file)
|
||||
if frontmatter and frontmatter.get("title"):
|
||||
valid_titles.add(frontmatter["title"])
|
||||
|
||||
# Collect all broken links and format issues
|
||||
# Collect all broken links
|
||||
broken_links: list[tuple[str, int, str]] = []
|
||||
unspaced_pipes: 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")):
|
||||
|
|
@ -117,45 +73,19 @@ def main() -> int:
|
|||
continue
|
||||
|
||||
rel_path = str(md_file.relative_to(DOCS_DIR))
|
||||
|
||||
# Check for unspaced pipes
|
||||
for link_text, line_num in find_unspaced_pipes(md_file):
|
||||
unspaced_pipes.append((rel_path, line_num, link_text))
|
||||
|
||||
# Check for broken links
|
||||
links = extract_wikilinks(md_file)
|
||||
|
||||
for target, line_num in links:
|
||||
if target not in valid_titles:
|
||||
if target not in valid_filenames:
|
||||
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(f"Found {len(valid_filenames)} valid filenames in documentation.")
|
||||
console.print()
|
||||
|
||||
has_errors = False
|
||||
|
||||
# Report unspaced pipes
|
||||
if unspaced_pipes:
|
||||
has_errors = True
|
||||
console.print("[bold red]Unspaced Pipe in Wiki-Links[/bold red]")
|
||||
console.print("Wiki-links with display text must use spaces: [[target | display]]")
|
||||
console.print()
|
||||
table = Table(show_header=True, header_style="bold")
|
||||
table.add_column("File")
|
||||
table.add_column("Line", justify="right")
|
||||
table.add_column("Link")
|
||||
|
||||
for file_path, line_num, link_text in unspaced_pipes:
|
||||
table.add_row(file_path, str(line_num), escape(link_text))
|
||||
|
||||
console.print(table)
|
||||
console.print()
|
||||
|
||||
# Report broken links
|
||||
if broken_links:
|
||||
has_errors = True
|
||||
console.print("[bold red]Broken Wiki-Links Found[/bold red]")
|
||||
table = Table(show_header=True, header_style="bold")
|
||||
table.add_column("File")
|
||||
|
|
@ -167,12 +97,9 @@ def main() -> int:
|
|||
|
||||
console.print(table)
|
||||
console.print()
|
||||
console.print("Each wiki-link target must match a frontmatter title in docs/.")
|
||||
console.print(f"[bold red]{len(broken_links)} broken link(s) found.[/bold red]")
|
||||
console.print()
|
||||
|
||||
if has_errors:
|
||||
error_count = len(broken_links) + len(unspaced_pipes)
|
||||
console.print(f"[bold red]{error_count} issue(s) found.[/bold red]")
|
||||
console.print("Each wiki-link target must match a filename in docs/.")
|
||||
return 1
|
||||
|
||||
console.print("[bold green]All wiki-links are valid![/bold green]")
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue