Skip to main content

Docusaurus To-Do List

Last Updated: 2026-01-07
Planned features, improvements, and recurring tasks for the Docusaurus documentation site.

📊 Progress Overview​

📦 Archive (2026)​

January 2026 Implementations​

TwentyCRM Sync System (Completed: 2026-01-08)​

Quality: ⭐⭐⭐⭐⭐ Production-ready with full note linking
Components: scripts/sync-tools/sync.js, scripts/sync-tools/generate-note.js, docusaurus/scripts/sync-notes.cjs, ToolOverviewButton component
Features Delivered:

  • Two-way sync for account data (TwentyCRM ↔ Local frontmatter)
  • One-way sync for notes (Local → TwentyCRM only)
  • AI-powered note generation using Gemini API with Pacing Agency context
  • Automatic note linking via /noteTargets endpoint (ensures proper relationships)
  • Duplicate note prevention (deletes old notes, creates new with proper linking)
  • Mermaid diagram stripping (TwentyCRM doesn't support them)
  • Build-time sync pulls latest account data from TwentyCRM
  • Generated notes displayed in Docusaurus via ToolOverviewButton component
  • Note context system for guiding AI generation (collapsible in Docusaurus)

Technical Implementation:

  • Account data syncs bidirectionally during build (sync.js --from-twentycrm)
  • Notes sync one-way only (Local → TwentyCRM) to preserve internal summaries
  • AI notes generated via Gemini 3 Flash with URL context and Google search grounding
  • Notes linked to accounts using /noteTargets endpoint (not via note object's noteTargets field)
  • Generated notes stored in scripts/sync-tools/generated-notes/ (gitignored)
  • Notes synced to docusaurus/static/notes/ during build for ToolOverviewButton access
  • React component lazy-loads note content on demand

Follow-ups:

  • Improve remaining tool documentation files before generating notes
  • Generate notes for all tools incrementally
  • Monitor note quality and refine prompts as needed

Algolia Search Integration (Completed: 2026-01-07)​

Quality: ⭐⭐⭐⭐⭐ Production-ready with API-based indexing
Components: docusaurus.config.ts, index-algolia.cjs, SearchBar/index.tsx (custom Hit component), custom.css, algolia-search.md
Features Delivered:

  • Algolia DocSearch with fast, relevant search results
  • Ask AI feature for conversational, natural language queries (currently disabled due to API issues)
  • API-based indexing (bypasses Cloudflare Access protection)
  • Automatic indexing on every build via postbuild hook
  • Custom Hit component for proper search result rendering
  • Custom styling matching brand colors in both light and dark modes
  • Keyboard shortcuts (Ctrl+K / Cmd+K) for quick access
  • Contextual search filtering by section and category
  • Comprehensive documentation with troubleshooting guide
  • Multiple records per page (one per heading section) for better content snippets

Technical Implementation:

  • Indexing script extracts content from built HTML files
  • Creates multiple records per page (one per heading) for granular search results
  • Pushes records to Algolia via Admin API (not crawler-based)
  • Custom Hit component manually renders hierarchy, title, and content snippets
  • Configures searchable attributes and ranking
  • Environment variables for local dev (.env) and production (Cloudflare Pages)
  • Search-only API key is public (safe to commit)
  • Admin API key is secret (environment variables only)

Follow-ups:

  • Monitor search usage and performance in Algolia dashboard
  • Add search analytics to track popular queries
  • Consider adding suggested searches or "Did you mean?" functionality
  • Review and optimize index settings based on usage patterns

Tool Categorization & Metadata System (Completed: 2026-01-03)​

Quality: ⭐⭐⭐⭐⭐ Production-ready with full CSV integration
Components: sync-tools.cjs, CategorySummary, ToolMetadata, ToolsOverview, sections.ts
Features Delivered:

  • Tools organised by 9 categories (Website, Self-Hosting, Operational, Social, Marketing, Design, Ad Spend, Office, Uncategorised)
  • CSV-based metadata sync from TwentyCRM (costs, renewals, account types, access links)
  • Beautiful colour-coded metadata cards on tool pages
  • Visual category summary cards with cost totals
  • Interactive expandable category overview on main tools page
  • Auto-calculation of annual costs from monthly when not provided
  • Real-time visibility: £582.56/month, £6,990.72/year total

Follow-ups:

  • Create 4 missing tool docs (London Cycling Insta, Cycling London Insta, Resend, Image Compressor)
  • Consider adding cost trend visualisations (month-over-month changes)
  • Add renewal alerts for tools expiring in next 30/60/90 days

Documentation Quality & Validation (Completed: 2026-01-06)​

Quality: ⭐⭐⭐⭐⭐ Comprehensive automation suite
Components: check-links.cjs, verify-docs.cjs, validate-mdx.cjs, GitHub Actions CI
Features Delivered:

  • Link checker with external/internal link validation (detects broken links)
  • Documentation verification with auto-update of "Last verified" dates
  • Flags outdated docs (>90 days since verification)
  • MDX syntax validation before build (prevents deployment errors)
  • Unit tests for all validation scripts
  • GitHub Actions CI for automated testing on every push

Follow-ups:

  • Add visual dashboard showing documentation health metrics
  • Consider email notifications for broken links
  • Add checks for outdated screenshots
  • Flag missing best practices sections

Component Library & Templates (Completed: 2026-01-06)​

Quality: ⭐⭐⭐⭐⭐ Production-ready reusable components
Components: Callout, FAQ, ToolMetadata, CategorySummary, ToolsOverview, CopyDownloadButton
Features Delivered:

  • Callout component with 5 variants (Info, Warning, Danger, Success, Tip)
  • Collapsible callout support
  • FAQ component with structured data for SEO
  • Interactive CLI generator (npm run create-doc)
  • Ready-to-use templates (tool, feature, guide, custom page)
  • Copy/Download button on every page (plaintext, markdown, download)

Follow-ups:

  • Add more component examples to feature docs
  • Consider video tutorial component for complex setups
  • Add table-of-contents component for long docs
  • Create accordion/tabs component for content organisation

LLMs.txt Implementation (Completed: 2026-01-06)​

Quality: ⭐⭐⭐⭐⭐ Spec-compliant with automatic generation
Components: generate-llms-txt.cjs, prebuild hook integration
Features Delivered:

  • Auto-generation of /llms.txt following llmstxt.org specification
  • HTML markdown versions (.html.md) for web viewing
  • Includes all documentation sections with proper hierarchy
  • Updates automatically on every build
  • Optimised for AI consumption (Cursor, ChatGPT, Claude, etc.)

Follow-ups:

  • Monitor usage analytics to see if LLMs.txt is being accessed
  • Consider adding more structured metadata for AI tools
  • Add API documentation when available

Sections Configuration System (Completed: 2026-01-03)​

Quality: ⭐⭐⭐⭐⭐ Maintainable centralised config
Components: config/sections.ts, sidebars.ts integration
Features Delivered:

  • Centralised configuration for all documentation sections
  • Section status management (planned, active, deprecated, archived)
  • Easy addition of new top-level sections (Prompts, Processes planned)
  • Auto-generation of sidebar config from sections
  • Version control and audit trail for section changes

Follow-ups:

  • Activate Prompts section (currently planned)
  • Activate Processes section (currently planned)
  • Consider analytics section for usage dashboards

Maintenance & Documentation Completed​

Tool Documentation Review (Completed: 2026-01-03)​

Quality: ⭐⭐⭐⭐ Comprehensive review completed
Scope: All 54 tool documentation files reviewed for consistency
Follow-ups: Keep updated as new tools are added

Metadata Verification (Completed: 2026-01-03)​

Quality: ⭐⭐⭐⭐⭐ All tools have proper frontmatter
Scope: 39/44 tools matched from TwentyCRM CSV
Follow-ups: Create 4 missing tool docs

Generated Files Verification (Completed: 2026-01-03)​

Quality: ⭐⭐⭐⭐⭐ All auto-generated files correct
Scope: Tool docs, category pages, sidebar config all verified
Follow-ups: Monthly verification recommended

Quality: ⭐⭐⭐⭐⭐ Logical structure with categories
Scope: All sections properly organised and navigable
Follow-ups: Update when Prompts/Processes sections added

Component Documentation (Completed: 2026-01-06)​

Quality: ⭐⭐⭐⭐ Good documentation with examples
Scope: All major components documented in features section
Follow-ups: Add more usage examples and video tutorials

✅ Recently Completed (Active Development)​

Current features in production and ready for use:

  • Tool Categorization System - ⭐⭐⭐⭐⭐ Production-ready
  • Cost Tracking & Metadata - ⭐⭐⭐⭐⭐ CSV-synced, real-time
  • Visual Components - ⭐⭐⭐⭐⭐ Beautiful, responsive UI
  • Documentation Quality Tools - ⭐⭐⭐⭐⭐ Automated validation
  • Template System - ⭐⭐⭐⭐⭐ Interactive CLI generator
  • LLMs.txt - ⭐⭐⭐⭐⭐ Spec-compliant, auto-generated
  • Algolia Search - ⭐⭐⭐⭐⭐ API-based indexing with Ask AI
  • TwentyCRM Sync System - ⭐⭐⭐⭐⭐ Two-way account sync, one-way note sync with AI-powered overview generation

🚀 Planned Features​

High Priority​

  • Search improvements - ✅ Algolia DocSearch implemented with API-based indexing and Ask AI feature
  • Analytics integration (planning) - ✅ Comprehensive implementation plan created in docs/ANALYTICS_IMPLEMENTATION.md
  • Prompts section - ✅ Structure complete with 5 category landing pages, ready for individual prompts to be added incrementally
  • Prompt button feature - ✅ Production-ready with 4 platform formatters (Cursor, ChatGPT, Gemini, Universal)
  • Individual prompt templates - Add 19 remaining prompts incrementally (1 Hetzner example complete, templates ready)
  • Versioning support - Add versioning for tool documentation when tools are updated
  • CSV Auto-sync - Automate CSV export from TwentyCRM and update tool metadata

Medium Priority​

  • Tool Health Dashboard - Visual status showing renewals, cost trends, outdated docs
  • Client Handoff Generator - Export filtered tool docs as PDF with credentials
  • Integration Flow Visualizer - Interactive diagrams showing tool connections
  • Dependency Mapping - Visual tool relationship graph with impact analysis
  • API documentation - Generate API docs from code comments

Low Priority​

  • Blog section - ✅ Already exists with 8 published posts (tech stack, FAQs, WordPress migration, User ID, website data)
  • Dark mode improvements - ⚠️ Works well except Mermaid diagrams need theme adjustments
  • Mobile optimisation - ⚠️ Needs comprehensive testing across components
  • Accessibility audit - Ensure WCAG compliance across all components
  • Video tutorials - Embed walkthrough videos for complex setups

🔄 Recurring Tasks​

Weekly​

  • Review pull requests - Check for documentation updates
  • Test build - Verify site builds successfully
  • Check broken links - Manual check of critical pages

Monthly​

  • Update tool docs - Review and update outdated tool documentation
  • Clean up generated files - Ensure no manual edits to generated files
  • Review to-do list - Update priorities and add new items
  • Check deployment - Verify Cloudflare Pages deployment is working

Quarterly​

  • Architecture review - Update architecture.md with current stack
  • Feature audit - Review and document new features added
  • Performance check - Review site performance and loading times
  • Security audit - Check dependencies for vulnerabilities

🤖 Automation Opportunities​

Can Be Automated​

  • ✅ Auto-sync tools - Already automated with category organization
  • ✅ MDX validation - Already automated
  • ✅ Build and deploy - Already automated
  • ✅ Tool metadata extraction - Already automated from CSV
  • ✅ Category page generation - Already automated
  • ✅ Tool index generation - Already automated with interactive overview
  • ✅ Link checking - Already automated with check-links script
  • ✅ Last verified dates - Already automated with verify-docs script
  • ✅ Automated testing - Unit tests with GitHub Actions CI integration
  • CSV auto-import - Automate TwentyCRM export and sync

Manual (For Now)​

  • Content review - Review documentation quality and completeness
  • Architecture updates - Update when tech stack changes
  • Feature documentation - Document new features as they're added

📋 Maintenance Tasks​

Immediate​

  • Review all tool docs for consistency ✅
  • Ensure all tools have proper metadata ✅
  • Verify all generated files are correct ✅
  • Check sidebar navigation is logical ✅
  • Document new components (ToolMetadata, CategorySummary, ToolsOverview, PromptButton) ✅
  • Document link checker and doc verification features ✅
  • Document mobile testing requirements ✅
  • Create 4 missing tool docs (London Cycling Insta, Cycling London Insta, Resend, Image Compressor)
  • Add 19 remaining individual prompt templates (infrastructure: 4, development: 5, marketing: 5, client work: 5)

Short-term​

  • Create component library documentation (Callout, PromptButton components)
  • Add templates for new documentation (tool, feature, guide, custom, prompt templates)
  • Create Prompts section with category structure
  • Add 19 remaining individual prompt templates
  • Add more examples to feature docs
  • Improve search functionality
  • Implement analytics tracking on docs site
  • Add more visual diagrams to architecture docs
  • Test mobile responsiveness on real devices

Long-term​

  • Migrate to Docusaurus v4 when stable
  • Implement versioning for major tool updates
  • Add multi-language support
  • Create client-facing documentation site

🐛 Known Issues​

  • None currently - all issues resolved ✅

💡 Ideas for Future​

Agency Operations & Management​

  1. Tool Health Dashboard - Visual status page showing:

    • Tools approaching renewal dates (next 30/60/90 days)
    • Cost trends over time (month-over-month changes)
    • Tools without recent documentation updates (>90 days)
    • Account access status (who has access to what)
    • Priority: High | Effort: Medium

  2. Automated Cost Reporting - Weekly/monthly email digest:

    • Total monthly spend vs budget
    • New tools added this period
    • Upcoming renewals with cost impact
    • Cost optimisation opportunities (duplicate tools, unused subscriptions)
    • Priority: High | Effort: Medium

  3. Client Handoff Generator - Export tool documentation for client handoff:

    • Filter by client-relevant tools only
    • Generate PDF with credentials/access info
    • Include setup guides and maintenance notes
    • White-label with client branding
    • Priority: High | Effort: High

  4. Dependency Mapping - Visual tool relationship graph:

    • Show which tools depend on others (e.g., Webflow → GTM → sGTM → BigQuery)
    • Impact analysis for changes ("If we change X, what breaks?")
    • Client vs internal tool separation
    • Export as client-facing documentation
    • Priority: Medium | Effort: High

  5. Capacity Planning Dashboard - Resource tracking:

    • Server capacity (Hetzner usage, CPU, RAM, disk)
    • API rate limits (approaching limits warnings)
    • Storage usage trends across all services
    • Performance benchmarks and alerts
    • Priority: Medium | Effort: Medium

  6. Team Skill Matrix - Who knows what:

    • Tool expertise by team member
    • Training needs identification
    • On-call rotation readiness
    • Knowledge gap analysis
    • Priority: Low | Effort: Low

Client-Facing Features​

  1. Client Portal Integration - Subset of docs for clients:

    • Read-only view of their specific tools
    • Filtered guides relevant to their tech stack
    • Custom branding per client
    • Track what clients actually read (engagement analytics)
    • Priority: High | Effort: High

  2. Integration Flow Visualizer - Interactive diagrams showing:

    • How tools connect in data flows
    • Click nodes to see configuration details
    • Real-time status indicators
    • Export as client-facing documentation
    • Priority: High | Effort: High

  3. Incident Response Playbooks - Quick-reference guides:

    • Site down checklist with escalation paths
    • Tracking not working troubleshooting tree
    • Common error messages and instant fixes
    • Automated diagnosis tools where possible
    • Priority: High | Effort: Medium

Documentation & Content​

  1. Knowledge Base Search Enhancement - AI-powered search:

    • Natural language queries ("How do I set up tracking for a new client?")
    • Context-aware results with relevance ranking
    • Search analytics (what people can't find = content gaps)
    • Suggested related documentation
    • Priority: Medium | Effort: High

  2. Tool Comparison Matrix - Side-by-side tool comparison:

    • Alternative tool suggestions for cost optimisation
    • Feature comparison tables
    • Cost vs capability analysis
    • "Why we chose X over Y" documentation with decision rationale
    • Priority: Low | Effort: Low

  3. Automated Documentation Quality Checks - Content validation:

    • Scan for outdated screenshots (image hash comparison)
    • Check for broken code examples (syntax validation)
    • Verify all IDs/credentials are documented
    • Flag missing best practices sections
    • Priority: Medium | Effort: Medium

  4. Glossary/Terminology - Centralised definitions:

    • Agency-specific terms and jargon
    • Tool-specific terminology with context
    • Acronym expansion (GTM, sGTM, CMP, CAPI, etc.)
    • Cross-referenced throughout all docs
    • Priority: Low | Effort: Low

  5. Video Tutorials - Embed walkthrough videos:

    • Screen recordings for complex setups
    • Narrated step-by-step guides
    • Client testimonials and case studies
    • Tool demos showing real workflows
    • Priority: Medium | Effort: High

  6. Interactive Examples - Live code/config examples:

    • GTM tag configuration playgrounds
    • n8n workflow builders with templates
    • Webflow CMS structure visualisers
    • Test environments for safe experimentation
    • Priority: Medium | Effort: Very High

Automation & Integration​

  1. Change Log Automation - Git-based changelog:

    • Auto-generate from commit messages
    • Tool-specific change history
    • Client-facing vs internal changes separated
    • Breaking changes highlighted with migration guides
    • Priority: Medium | Effort: Medium

  2. Workflow Templates - Step-by-step checklists for:

    • New client onboarding (discovery → setup → launch)
    • Website migration (audit → plan → execute → verify)
    • Tracking implementation (setup → test → document)
    • Crisis response procedures (detect → diagnose → resolve → prevent)
    • Priority: High | Effort: Low

  3. Prompt Library Enhancement - Beyond basic prompts:

    • Version control for prompts (track what works over time)
    • Prompt performance metrics (success rate, time saved)
    • Team feedback on prompt effectiveness
    • Client-specific prompt customisation
    • Priority: Medium | Effort: Medium

Contributing​

To add items to this to-do list:

  1. Add to appropriate section (Planned Features, Recurring Tasks, etc.)
  2. Use checkboxes - - [ ] for incomplete, - [x] for complete
  3. Be specific - Clear description of what needs to be done
  4. Prioritise - Use High/Medium/Low priority labels
  5. Link to issues - Reference GitHub issues if applicable