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.

• 1.1 Create src/types.ts with basic shared type definitions
  • Doc interface
  • Config interface
  • Heading interface
• 1.2 Locate and identify any existing types files
• 1.3 Update imports in all files to use the new types.ts
  • Ensure imports are properly organized and not duplicated
• 1.4 Remove old types files after confirming all imports are updated
• 1.5 Run vt push to test basic structure - Note: Needs to be executed manually

• 2.1 Create src/utils.ts with helper functions
  • loadDoc function with proper path handling and error management
  • DocTreeNode interface
  • NestedGroupedDocs interface
  • groupByFolder function (renamed from groupDocsByFolder)
  • generateTableOfContents function
• 2.2 Update App.tsx to use the new utils.ts
  • Remove duplicate imports
  • Remove duplicate function declarations
  • Update function calls to use new names (e.g., groupByFolder)
• 2.3 Run vt push to test utility functions

• 3.1 Create src/plugins.ts with remark/rehype plugins
  • remarkCallout plugin with fixed regex pattern
  • rehypeCallout plugin
  • Include proper imports (visit, SKIP, etc.)
• 3.2 Update App.tsx to use the new plugins.ts
  • Remove duplicate plugin implementations
  • Ensure proper imports
• 3.3 Run vt push to test plugins

• 4.1 Create src/parser.ts with unified parser setup
  • Import and configure remark plugins
  • Import and configure rehype plugins
  • Remove remarkLint (move to dev chain) - Ensure proper error handling- [ ] 4.2 Update App.tsx to use the new parser.ts - Remove duplicate parser setup
  • Ensure proper imports- [ ] 4.3 Run vt push to test parser

• 5.1 Create src/config.ts
  • Define config object with all settings
  • Create helper to resolve all stylesheet paths once
  • Define docs array with document list
  • Ensure document paths are correctly formatted
• 5.2 Remove any existing config files or duplicate configuration code
• 5.3 Update App.tsx to use the new config.ts
  • Ensure proper imports
  • Remove duplicate configuration
• 5.4 Run vt push to test configuration

• 6.1 Create src/builders/navigation.ts
  • buildNav function (renamed from docLinksHtml)
  • buildSidebar function (renamed from sidebarHtml)
• 6.2 Remove navigation-related functions from App.tsx
• 6.3 Update App.tsx to use the new navigation.ts
  • Ensure proper imports
• 6.4 Run vt push to test navigation

• 7.1 Create src/builders/head.ts
  • buildHead function
• 7.2 Remove head-related functions from App.tsx
• 7.3 Update App.tsx to use the new head.ts
• 7.4 Run vt push to test head builder

• 8.1 Create src/builders/scripts.ts
  • buildScripts function
• 8.2 Remove scripts-related functions from App.tsx
• 8.3 Update App.tsx to use the new scripts.ts
• 8.4 Run vt push to test scripts builder

• 9.1 Enhance utils.ts with buildToc function
• 9.2 Create src/handlers.ts
  • renderDoc function (renamed from processDocument)
  • appHandler function (renamed from handleRequest)
• 9.3 Remove handler-related functions from App.tsx
• 9.4 Update App.tsx to use the new handlers.ts
• 9.5 Run vt push to test handlers

• 10.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
• 10.2 Run vt push to test final implementation
• 10.3 Verify all functionality works as expected

• Ensure old utility functions are removed from App.tsx as they're moved to utils.ts
• Ensure old plugin definitions are removed from App.tsx as they're moved to plugins.ts
• Ensure old parser setup is removed from App.tsx as it's moved to parser.ts
• Ensure old configuration is removed as it's moved to config.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

• 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