Skip to content

Link docs hierarchy from README and fix broken design references#166

Merged
hackerwins merged 1 commit into
mainfrom
link-connectivity-fix
Apr 29, 2026
Merged

Link docs hierarchy from README and fix broken design references#166
hackerwins merged 1 commit into
mainfrom
link-connectivity-fix

Conversation

@hackerwins

@hackerwins hackerwins commented Apr 29, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Collaborator

Summary

  • Convert the Project Structure code block in `README.md` to a markdown list so all six package READMEs become reachable from the entry point. Add a Documentation section linking `docs/`, `MAINTAINING.md`, and `CLAUDE.md` (also exposed as `AGENTS.md` via symlink).
  • Fix `docs/README.md` so `design/` and `tasks/` point at the README.md inside each subdirectory (the previous `(design/)` and `(tasks/)` targets lacked a `.md` extension and were skipped by link checkers).
  • Add `docs-docx-import-export.md` and `template.md` to `docs/design/README.md` so they are reachable from the design index.
  • Link `active/README.md` and `archive/README.md` from `docs/tasks/README.md` (they were referenced inline by code-style paths previously).
  • Add the two pre-todo `-plan.md` files (`docs-site`, `docs-arrow-pixel-accuracy`) to `docs/tasks/archive/README.md` under a legacy plans subsection.
  • Link `index.md` from `packages/documentation/README.md` so the VitePress landing redirect is reachable.
  • Fix four broken design references in tasks. The relative paths needed one or two more parent hops to reach `docs/design/`:
    • `archive/2026/04/20260411-docs-table-merge-ux-todo.md`: `../../design/...` → `../../../../design/...`
    • `archive/2026/04/20260408-header-footer-todo.md`: same fix
    • `active/20260325-docs-wordprocessor-todo.md`: `../../design/docs-wordprocessor-roadmap.md` → `../../design/docs/docs-wordprocessor-roadmap.md`
    • `active/20260325-docs-wordprocessor-lessons.md`: same fix

Found via the link connectivity check script being added to second-brain (yorkie-team/second-brain#34).

Before this change, 319 `.md` files in this repo had no incoming link from the README graph. After, only the `.github/` issue/PR templates and the `AGENTS.md → CLAUDE.md` symlink remain (both are by design).

Test plan

  • Verified the corrected design paths resolve to existing files
  • Verified the new Documentation/Project Structure links resolve
  • Reviewer to spot-check the new and updated index sections

Summary by CodeRabbit

  • Documentation
    • Reorganized main README's Project Structure section with linked navigation to package documentation and new Documentation section surfacing design, architecture, and task tracking resources.
    • Enhanced docs navigation with clickable task category links (Active and Archived tasks).
    • Added DOCX import/export design documentation reference.
    • Improved internal documentation cross-references and file path consistency across task and design documents.

@hackerwins
Link docs hierarchy from README and fix broken design references
619b8a4 
The README's Project Structure was a code block, so the link parser saw
no outgoing links to the package READMEs. Convert it to a markdown list
so packages/sheets, packages/docs, packages/frontend, packages/backend,
packages/cli/skills, and packages/documentation are all reachable from
the project's entry point. Add a Documentation section linking docs/,
MAINTAINING.md, and CLAUDE.md (also exposed as AGENTS.md via symlink).

In docs/README.md, the design/ and tasks/ entries used \`(design/)\` and
\`(tasks/)\` style targets that lack a \`.md\` extension, so the link
checker treated them as non-doc. Point them at the README.md inside
each subdirectory.

Add docs-docx-import-export.md and template.md to docs/design/README.md
so they are reachable from the design index.

Link active/README.md and archive/README.md from docs/tasks/README.md
(they were referenced inline by code-style paths previously).

Add the two pre-todo \`-plan.md\` files (docs-site, docs-arrow-pixel-accuracy)
to docs/tasks/archive/README.md under a legacy plans subsection.

Link index.md from packages/documentation/README.md so the VitePress
landing redirect is reachable.

Fix four broken design references in tasks. The relative paths needed
one or two more parent hops to reach docs/design/:
- archive/2026/04/20260411-docs-table-merge-ux-todo.md
- archive/2026/04/20260408-header-footer-todo.md
- active/20260325-docs-wordprocessor-todo.md
- active/20260325-docs-wordprocessor-lessons.md
@coderabbitai

coderabbitai Bot commented Apr 29, 2026 •
edited
Loading

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ce0e665d-e4cd-400d-b510-3f9ae34c6656

📥 Commits

Reviewing files that changed from the base of the PR and between b22f156 and 619b8a4.

📒 Files selected for processing (10)
  • README.md
  • docs/README.md
  • docs/design/README.md
  • docs/tasks/README.md
  • docs/tasks/active/20260325-docs-wordprocessor-lessons.md
  • docs/tasks/active/20260325-docs-wordprocessor-todo.md
  • docs/tasks/archive/2026/04/20260408-header-footer-todo.md
  • docs/tasks/archive/2026/04/20260411-docs-table-merge-ux-todo.md
  • docs/tasks/archive/README.md
  • packages/documentation/README.md
📝 Walkthrough

Walkthrough

Documentation restructuring PR that reorganizes the main README project structure into linked markdown bullets, introduces a Documentation section with architecture and design references, updates documentation navigation to use README.md files, and corrects cross-reference links throughout design and task documents to reflect new file organization in docs subdirectories.

Changes

Cohort / File(s) Summary
Main README restructuring
README.md		 Converts unlinked directory tree to explicit markdown bullets with links to package READMEs, adds new Documentation section linking to design/architecture/maintenance docs.
Documentation navigation updates
docs/README.md, docs/tasks/README.md, docs/tasks/archive/README.md, packages/documentation/README.md		 Updates documentation index and table links to point to README.md files instead of directory paths; adds archive subsection for legacy plan items; clarifies index.md redirect behavior.
Design documentation index
docs/design/README.md		 Adds DOCX import/export design document reference; updates template guidance to point to template.md file instead of inline instructions.
Task document cross-references
docs/tasks/active/20260325-docs-wordprocessor-*.md, docs/tasks/archive/2026/04/20260408-header-footer-todo.md, docs/tasks/archive/2026/04/20260411-docs-table-merge-ux-todo.md		 Corrects relative paths in design doc hyperlinks to reflect new docs subdirectory organization (e.g., ../../design/docs-*.md → ../../design/docs/docs-*.md).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

Poem

🐰 Hop through docs with links so neat,
Files reorganized, structure complete!
From flat to nested, paths now clear,
Navigation's better, files appear! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main changes: converting README documentation structure to improve link connectivity and fixing broken design document references across the codebase.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch link-connectivity-fix

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share
Review rate limit: 0/1 reviews remaining, refill in 60 minutes.

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented Apr 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Verification: verify:self

Result: ✅ PASS in 119.1s

Lane Status Duration
sheets:build ✅ pass 13.3s
docs:build ✅ pass 8.1s
verify:fast ✅ pass 60.6s
frontend:build ✅ pass 15.6s
verify:frontend:chunks ✅ pass 0.3s
backend:build ✅ pass 4.7s
cli:build ✅ pass 1.8s
verify:entropy ✅ pass 14.7s

Verification: verify:integration

Result: ✅ PASS

@codecov

codecov Bot commented Apr 29, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@hackerwins
hackerwins merged commit a571fd6 into main Apr 29, 2026
4 checks passed
@hackerwins
hackerwins deleted the link-connectivity-fix branch April 29, 2026 07:51
@hackerwins hackerwins mentioned this pull request May 1, 2026
Merged
3 tasks
@coderabbitai coderabbitai Bot mentioned this pull request May 9, 2026
Merged
2 tasks
@coderabbitai coderabbitai Bot mentioned this pull request May 17, 2026
Merged
6 tasks
@coderabbitai coderabbitai Bot mentioned this pull request Jun 7, 2026
Merged
@coderabbitai coderabbitai Bot mentioned this pull request Jul 23, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@hackerwins