Skip to content

Conversation

@m1ngsama
Copy link
Member

Summary

Add comprehensive terminal-based documentation viewer that allows users to browse and read Markdown files from the nbtca/documents repository directly in the terminal, eliminating the need to open a browser.

Features Implemented

  • GitHub API Integration: Fetch directory structure and file contents from nbtca/documents repository
  • Directory Tree Navigation: Browse documentation categories with recursive directory navigation
  • VitePress Syntax Cleaning: Remove frontmatter, containers (:::info, :::tip), [[toc]], and HTML comments for clean terminal rendering
  • Terminal Markdown Rendering: Use marked-terminal for readable terminal output
  • Browser Fallback: Automatically offer to open browser on network errors or user preference
  • Retry Mechanism: Handle failed network requests gracefully

Technical Details

  • Uses GitHub Contents API and raw.githubusercontent.com for fetching
  • Implements cleanMarkdownContent() to strip VitePress-specific syntax
  • Recursive browseDirectory() function for stateless navigation
  • ASCII symbols: [DIR], [MD], [..], [ <], [ ^], [ *]
  • Integration with existing menu system

Testing Instructions

  1. Run pnpm run dev
  2. Select "[*] Knowledge Base" from main menu
  3. Navigate through categories using arrow keys or j/k
  4. Select any .md file to view rendered content
  5. Test back navigation with [..] and [ ^] options
  6. Test browser fallback with "[ *] Open in browser"

Files Changed

  • src/features/docs.ts: Complete rewrite with full implementation

Related Issues

Implements terminal documentation viewing as requested for better developer experience and terminal-first workflow.

- Implement GitHub API integration for documents repository
- Add directory tree navigation with [DIR] and [MD] indicators
- Implement VitePress syntax cleaning (frontmatter, containers)
- Add terminal Markdown rendering using marked-terminal
- Support browser fallback on errors
- Add retry mechanism for failed network requests

Features:
- Browse documentation categories
- Navigate directory structure
- View Markdown files in terminal
- Clean VitePress-specific syntax
- Fallback to browser when needed

Closes #TBD
@m1ngsama m1ngsama merged commit afbcaa7 into main Nov 27, 2025
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants