.linkcheck-ignore

# Known Broken Links - Documentation Only

## Purpose
This file documents known broken links in the documentation that are:
1. Expected/intentional (test files, brainstorm references)
2. External references outside the docs/ directory
3. Planned for future implementation

## Usage

This file is parsed by `/craft:docs:check-links` to distinguish between:
- **Critical broken links** (not in this file) → Exit code 1, blocks CI
- **Expected broken links** (documented here) → Exit code 0, shown as warnings

### Format

```markdown
### Category Name
File: `path/to/file.md`
Target: `path/to/target.md`
- Purpose: Why this link is expected to be broken

### Multiple Files/Targets
Files with broken links:
- `path/to/file1.md`
- `path/to/file2.md`

Targets: `target/pattern/*.md`
```

### Pattern Support
- **Exact paths**: `File: docs/test.md` matches exactly
- **Glob patterns**: `Files: docs/specs/*.md` matches all spec files
- **Any target**: Omit `Target:` line to ignore all broken links in file
- **Path normalization**: `docs/path` and `../path` are equivalent

## Categories

### 1. Test Violation Files (Intentional)
File: `docs/test-violations.md`
- Purpose: Test data for `craft:docs:check-links` and `craft:docs:lint`
- Contains intentionally broken links to verify linting works
- Should NOT be fixed

### 2. Archived Specs (Frozen References)
Files with broken links:
- `docs/specs/_archive/*.md`

- Reason: Archived specs contain stale relative links to brainstorm files, sibling specs, and docs that moved. These are frozen historical documents and won't be updated.

### 2b. Archived Docs (Frozen References)
Files with broken links:
- `docs/archive/*.md`

- Reason: Archived standalone docs contain stale relative links from when they lived at docs/ root. These are frozen historical documents and won't be updated.

### 3. README References (Outside Docs)
Files with broken links:
- `docs/TEACHING-DOCS-INDEX.md`

Target: `../README.md` (repository root, not in docs/)
- README.md is not published to documentation site
- Fix: Copy relevant content to docs/ or link to GitHub

### 4. Individual Command Pages (Not Implemented)
Files with broken links:
- `docs/TEACHING-DOCS-INDEX.md`
- `docs/teaching-migration.md`

Targets:
- `../commands/site/publish.md`
- `../commands/site/progress.md`
- `../commands/site/validate.md`
- `../commands/site/build.md`
- `../commands/site/create.md`
- `../commands/site/deploy.md`
- `../commands/site/check.md`
- `../commands/git/worktree.md`
- `../commands/git/branch.md`
- `../commands/git/sync.md`

Reason: Commands are documented in category files (e.g., `commands/site.md`, `commands/git.md`), not individual pages
Fix: Update links to point to category pages with anchors (e.g., `commands/site.md#publish`)

### 5. Manual Testing Checklist (Outside Docs)
File: `docs/guide/teaching-workflow.md`
Target: `../../tests/MANUAL-TESTING-CHECKLIST.md`

Reason: Test files are not published to documentation site
Fix: Remove reference or copy checklist to docs/

### 6. Command Documentation Examples
Files with broken links:
- `commands/docs/check-links.md` (contains intentional example broken links)
- `docs/git-init-docs-index.md` (reference to help/hub.md as example)
- `docs/archive/TEST-VALIDATION.md` (test output examples)
- `docs/reference/documentation-quality.md` (link pattern examples)

Targets:
- `../other.md`
- `../file.md`
- `file.md`
- `file.md#heading`
- `file.md#section`
- `/docs/file.md`
- `help/hub.md`
- `index.md`
- `index.md#overview`
- `./other-file.md`
- `../parent-file.md`
- `./file.md#section`
- `url`
- `../missing-file.md`
- Reason: These are intentional example links shown in documentation to illustrate what broken links look like
- Fix: Not needed - examples are correct as-is

### 7. Template Placeholders (NEW in v2.10.0)
Files with broken links:
- `templates/claude-md/teaching-template.md`
- `templates/claude-md/r-package-template.md`
- `templates/claude-md/mcp-server-template.md`

Targets (template variables):
- `{course_url}`
- `{repo_url}`
- `{canvas_url}`
- `{package_name}`
- `{github_org}`
- Any link containing `{variable}` pattern

Reason: Template files contain placeholder variables that are replaced when scaffolding new projects
Fix: Not needed - templates are correct and functional

### 8. Badge Management Documentation (v2.11.0)
Files with broken links:
- `docs/specs/SPEC-badge-system-2026-01-30.md`

Targets:
- `... 2.9.0 ...`
- `... 2.10.0-dev ...`

- Reason: Spec contains diff examples with pseudo-badge markdown
- Note: `badge-management.md` links fixed in docs-gap-fill PR

### 8b. Tutorial Test File References
Files with broken links:
- `docs/tutorials/TUTORIAL-craft-001-emoji-spacing.md`

Targets:
- `../../tests/test_craft_001_emoji_spacing.py`

- Reason: Tutorial references test files outside the docs/ directory
- Fix: Not needed - link is informational, test files are not published

### 9. Planned Documentation (Not Yet Created)
Files with broken links:
- `commands/orchestrate/resume.md`
- `commands/git/init.md`

Targets:
- `../docs/SESSION-STATE-SCHEMA.md`
- `../docs/SESSION-TELEPORTATION.md`
- `../../docs/help/ci-generate.md`
- `../../docs/WORKFLOWS/git-feature-workflow.md`
- `../../docs/WORKFLOWS/pre-commit-workflow.md`
- Reason: These reference planned documentation that will be created in future releases
- Fix: Create the referenced documentation files

### 10. Spec Brainstorm Cross-References
Files with broken links:
- `docs/specs/SPEC-website-organization-standard-2026-01-17.md`

Targets:
- `../brainstorm/BRAINSTORM-website-organization-2026-01-17.md`
- Reason: Specs reference brainstorm files that are gitignored and not published
- Fix: Update to GitHub blob URLs or remove references

## Build Status
- **Build command**: `mkdocs build --strict` will show these warnings
- **Expected**: ~30 warnings from categories above
- **Action required**: Fix categories #3, #4, #5, #8 in future PRs
- **No action needed**: Categories #1, #2, #6, #7 (intentional)

### 11. Template Pointer Links (v2.12.0 - CLAUDE.md v3)
Files with broken links:
- `templates/claude-md/plugin-template.md`

Targets:
- `docs/VERSION-HISTORY.md`
- `docs/ARCHITECTURE.md`

Reason: Pointer-format links (`->`) reference paths relative to the project root where the template will be instantiated, not relative to the template file location
Fix: Not needed - links are correct when template is used to scaffold a new CLAUDE.md

### 12. Spec Internal References (v2.12.0 - CLAUDE.md v3)
Files with broken links:
- `docs/specs/SPEC-claude-md-v3-optimization-2026-02-04.md`

Targets:
- `docs/VERSION-HISTORY.md`
- `docs/ARCHITECTURE.md`
- `CONTRIBUTING.md`
- `docs/COMMANDS.md`

Reason: Spec documents contain example pointer syntax (`->`) that demonstrates the format — these resolve from project root, not from spec file location
Fix: Not needed - these are examples of pointer syntax, not navigable links

### 13. Historical Release Notes References
Files with broken links:
- `CHANGELOG.md`

Targets:
- `DRY-RUN-SUMMARY.md`

Reason: Historical v1.20.0 changelog references a dry-run tracking document that was a working artifact, never committed
Fix: Not needed - historical changelog entry, document was ephemeral

## Next Steps (Phase 2+)
1. Update teaching docs to use category page anchors
2. Copy README teaching section to docs/ or use GitHub links
3. Consider removing brainstorm references from specs (or use GitHub URLs)
4. Decide: Keep test-violations.md or move to tests/

---
Created: 2026-01-17
Last updated: 2026-01-30
Related: PR #13 (Website Organization Phase 1), PR #39 (CLAUDE-MD suite)