This plan addresses refactoring, cleanup, organization, and key design principles (KISS, YAGNI, SoC, SRP, DRY) with beginner‑friendly names. Each step includes updating App.tsx for testing and pushing to Val Town.

• Create src/types.ts with basic shared type definitions
  • Doc interface
  • Config interface
  • Heading interface
• Update imports in all files to use the new types.ts
• Remove old types files after confirming all imports are updated
• Run vt push to test basic structure

• 1.1 Create src/plugins.ts by moving code from src/components/plugins.ts
  • remarkCallout plugin with fixed regex pattern
  • rehypeCallout plugin
  • Include proper imports (visit, SKIP, etc.)
• 1.2 Update App.tsx to use the new plugins.ts location
  • Update import path
  • Keep functionality identical
• 1.3 Run vt push to test plugins

• 2.1 Create src/config.ts by moving code from src/components/config.ts
  • Define config object with all settings
  • Define docs array with document list
  • Add helper to resolve all stylesheet paths once
• 2.2 Update App.tsx to use the new config.ts location
  • Update import path
  • Keep functionality identical
• 2.3 Run vt push to test configuration

• 3.1 Create src/builders/head.ts
  • Move headHtml function from App.tsx and rename to buildHead
• 3.2 Update App.tsx to use the new head.ts
  • Import buildHead function
  • Remove old headHtml function
• 3.3 Run vt push to test head builder

• 4.1 Create src/builders/scripts.ts
  • Move clientScripts function from App.tsx and rename to buildScripts
• 4.2 Update App.tsx to use the new scripts.ts
  • Import buildScripts function
  • Remove old clientScripts function
• 4.3 Run vt push to test scripts builder

• 5.1 Create src/builders/navigation.ts
  • Move docLinksHtml function and rename to buildNav
  • Move sidebarHtml function and rename to buildSidebar
• 5.2 Update App.tsx to use the new navigation.ts
  • Import buildNav and buildSidebar functions
  • Remove old docLinksHtml and sidebarHtml functions
• 5.3 Run vt push to test navigation

• 6.1 Create src/utils.ts with helper functions
  • Move loadDoc function with improved error handling
  • Move DocTreeNode interface
  • Move NestedGroupedDocs interface
  • Move and rename groupDocsByFolder to groupByFolder
  • Move generateTableOfContents function
  • Fix path handling in loadDoc to account for the new file location
• 6.2 Update App.tsx to use the new utils.ts
  • Update import paths
  • Update function calls to use new names
• 6.3 Update navigation.ts to import from the new utils.ts location
• 6.4 Run vt push to test utility functions
• 6.5 Remove old utils.ts file after confirming everything works

• 7.1 Create src/parser.ts with unified parser setup
  • Move parser configuration from App.tsx
  • Import and configure remark plugins
  • Import and configure rehype plugins
  • Remove remarkLint (move to dev chain)
  • Add proper error handling
• 7.2 Update App.tsx to use the new parser.ts
  • Import parser from new location
  • Remove duplicate parser setup
• 7.3 Run vt push to test parser

• 8.1 Create src/handlers.ts
  • Move processDocument function and rename to renderDoc
  • Move handleRequest function and rename to appHandler
• 8.2 Update App.tsx to use the new handlers.ts
  • Import appHandler function
  • Remove old handler-related functions
• 8.3 Run vt push to test handlers

• 9.1 Simplify App.tsx to be a thin wrapper
  • Import appHandler from src/handlers.ts
  • Export appHandler as default
  • Remove ALL remaining implementation code from App.tsx
• 9.2 Run vt push to test final implementation
• 9.3 Verify all functionality works as expected

• Ensure old plugin definitions are removed from App.tsx as they're moved to plugins.ts
• Ensure old configuration is removed as it's moved to config.ts
• Ensure old utility functions are removed from App.tsx as they're moved to utils.ts
• Ensure old parser setup is removed from App.tsx as it's moved to parser.ts
• Ensure old navigation functions are removed as they're moved to navigation.ts
• Ensure old head-building functions are removed as they're moved to head.ts
• Ensure old script-building functions are removed as they're moved to scripts.ts
• Ensure old handler functions are removed as they're moved to handlers.ts
• Verify no duplicate code exists between App.tsx and the new module files

• After each vt push, verify the app still works correctly
• If issues are found, fix them before moving to the next step
• Keep a backup of the working version before each major change
• Check browser console for any errors during testing
• When removing code from App.tsx, ensure it's properly moved to the new files first

• Basic formatting (headings, paragraphs, lists)
• Code blocks with syntax highlighting
• Inline code formatting
• Block quotes
• Tables
• Images
• Links (internal and external)
• Task lists
• Horizontal rules

• Callouts/admonitions (info, warning, error, etc.)
• Tabs
• Accordions/collapsible sections
• Custom tables with special formatting
• Code blocks with copy button
• Code blocks with line numbers
• Code blocks with line highlighting
• svgs

• Sidebar navigation works correctly
• Table of contents is generated properly
• Mobile responsiveness (sidebar toggle)
• Document switching works
• Nested folder structure displays correctly
• Active document is highlighted in navigation

• CSS is applied correctly
• Dark/light mode works if implemented
• Custom styling for markdown elements
• Print styling if implemented
• Responsive design at various screen sizes

• Page loads quickly
• No visible rendering delays
• No JavaScript errors in console
• Memory usage is reasonable

• Empty documents handle gracefully
• Very large documents render correctly
• Documents with many headings/TOC items
• Error handling for missing documents
• Special characters in markdown render correctly
• Nested markdown structures (lists within lists, etc.)

• Duplicate imports causing variable redeclaration errors
• Incorrect path handling in loadDoc function
• Inconsistent function naming (e.g., groupDocsByFolder vs groupByFolder)
• Missing error handling in async functions
• Incorrect relative paths when importing from new module files