feat: create comprehensive docs.page documentation structure #627
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Dramatically shortened README by 90% to focus on quick start - Created usecase-driven documentation with platform specifics integrated - Added comprehensive docs.page configuration with proper navigation - Created detailed platform setup guides (Android/iOS) - Added usecase-driven guides: data sync, file uploads, cleanup, notifications - Restructured documentation to be more actionable and user-focused - README now refers to docs.page for comprehensive documentation
|
To view this pull requests documentation preview, visit the following URL: docs.page/fluttercommunity/flutter_workmanager~627 Documentation is deployed and generated using docs.page. |
- Fixed docs.json from Mintlify format to simple docs.page format - Populated index.mdx with comprehensive content as main landing page - Added missing database-maintenance use case page - Simplified navigation structure for docs.page compatibility - Should resolve empty docs.page issue
- Fixed badges layout: converted to horizontal HTML img tags instead of vertical markdown - Removed invalid score badge as requested - Fixed use case links by using relative paths (usecases/data-sync) - Consolidated installation, setup, and quickstart into single comprehensive quickstart page - Removed duplicate setup pages (android.mdx, ios.mdx) to reduce clutter - Fixed example README - now shows actual features and usage instead of generic Flutter text - Streamlined navigation structure for better user experience - Front page now focused on intro/features/use case overview only
- Removed badges from docs.page index (cleaner look) - Fixed all domain references from hypothetical subdomain to actual docs.page URLs - Added comprehensive debugging page with Android job scheduler and iOS console debugging - Updated sidebar navigation to include debugging section - Made GitHub README links clearer with arrow indicators - Enhanced example README documentation link
- Converted <Tabs>, <CardGroup>, <AccordionGroup> components to standard markdown - Fixed 500 errors on use case pages by using platform-compatible syntax - Changed relative links to work properly with docs.page routing - All use case pages should now load without errors
- Fixed YAML frontmatter by removing quotes around title and description - This should resolve 500 errors on use case pages
- Simplified upload-files page by removing FilePicker dependency - Simplified fetch-notifications page by removing http/json imports - Focused on core Workmanager functionality rather than external dependencies
- Added _sidebar.md for mobile menu navigation - Fixed repetitive page titles (all use cases now marked as examples) - Made code examples mobile-friendly with shorter lines - Fixed invalid SQLite VACUUM command (changed to PRAGMA optimize) - Shortened variable names and function calls for better mobile display - Improved debugging commands for mobile viewing
- Shortened method names and variable declarations - Split long function calls across multiple lines appropriately - Removed verbose comments that take up mobile screen space - Made code more scannable on small screens
- Fixed _sidebar.md format with asterisks and leading slashes for docs.page compatibility - Removed duplicate H1 headings from all pages (frontmatter title is sufficient) - Mobile menu should now display properly with navigation items - Cleaner page titles without repetition
- Added sidebar.json for JSON-based navigation - Updated docs.json with navigation array - Trying multiple approaches to ensure mobile menu displays
- Remove _sidebar.md and sidebar.json that were causing conflicts - Update docs.json with proper docs.page sidebar structure using title/href - Fix mobile menu configuration for docs.page - Ensure all pages use correct frontmatter without duplicate H1 headings 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add 'tab: root' property to all sidebar groups - Organize navigation into Getting Started, Examples, and Reference groups - Follow official docs.page sidebar configuration format - Should fix mobile menu visibility issue 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add dark blue theme with higher contrast (#1e3a8a primary) - Remove redundant cross-links between use case pages (handled by sidebar) - Eliminate repetitive intro paragraph from quickstart page - Add Xcode Help link for Background Modes configuration - Add explanatory callout for iOS task identifier requirements - Improve user guidance and reduce confusion 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Fix callouts to use proper docs.page syntax (Info, Success components) - Improve color theme contrast for better light theme readability - Restructure iOS setup with clear decision tree: Periodic vs Processing tasks - Default to Background Fetch API (registerPeriodicTask) for common use cases - Add BGTaskScheduler option for complex operations requiring longer execution - Add Xcode 'Perform Fetch' debugging option to Xcode debugging section - Provide clear guidance on which API to choose based on use case 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Remove unnecessary registerPeriodicTask from Background Fetch setup - Clarify that only BGTaskScheduler (Option B) requires AppDelegate registration - Background Fetch (Option A) works automatically with just Info.plist setup - Update info callout to explain difference between the two approaches - Make it clear which setup steps apply to which iOS background API 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add warning that iOS Background Fetch runs typically once per day - Explain that scheduling is entirely controlled by iOS based on user patterns - Cannot force immediate execution - designed for non-critical updates - Update decision guidance to reflect daily scheduling limitation - Help users understand Background Fetch vs BGTaskScheduler timing differences 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add Option C: registerPeriodicTask with custom frequency control (15+ min) - Clarify three distinct iOS approaches: Background Fetch vs BGTaskScheduler vs Periodic - Remove debugging code from quickstart, link to dedicated debugging page - Fix confusing Xcode debugging: separate 'Perform Fetch' from BGTaskScheduler commands - Add Apple WWDC and upstream documentation links to Common iOS Issues - Include relevant Apple Support, Developer Documentation, and WWDC session links - Provide comprehensive guidance for iOS background task debugging 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Remove convoluted use case pages (data-sync, upload-files, etc.) - Eliminate 'Examples' section from navigation - now just Getting Started + Reference - Keep use case descriptions in main page table for overview without links - Focus documentation on essential guides: Overview, Quickstart, Debugging - Point users to example app for complete implementation reference - Cleaner, more focused documentation structure 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Add link to pub.dev API documentation in Get Started section - Provides users easy access to complete Dart API reference - Positioned after Quick Start Guide for natural discovery flow 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
Add Missing Features to Quickstart: - Task constraints (network, battery, storage, charging requirements) - Input data passing and access in background tasks - Task tagging and management (cancel by tag, unique name, all) - iOS requirements (Swift 4.2+, Xcode 10.3+, iOS 10+) Setup File Cleanup: - Remove android_setup.md and ios_setup.md (content now in docs.page) - Essential setup details integrated into quickstart guide README Improvements: - Remove redundant quickstart code (point to docs.page instead) - Fix broken use case links (use cases were removed) - Streamline documentation links to Quick Start, API docs, Debugging - Focus on high-level use case descriptions rather than detailed guides Ensures information parity with pub.dev while maintaining clean structure. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Move advanced features from quickstart to separate customization page - Keep quickstart focused on basic setup and usage - Add comprehensive customization guide covering: - Input data passing and access - Task constraints (network, battery, storage) - Task tagging and management - Cancellation methods - Error handling and retries - Best practices and resource management - Add to navigation under Reference section - Update quickstart Next Steps to reference customization page 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Include dart pub publish --dry-run workflow information - Document melos-based development setup and commands - Cover code generation, formatting, and testing procedures - Provide publishing checklist and version management guide - Include platform-specific testing guidelines - Document CI workflows and common troubleshooting - Preserve maintainer knowledge previously in setup docs 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
Quickstart improvements: - Remove outdated iOS requirements (Swift 4.2+, Xcode 10.3+, iOS 10+) - Combine repetitive setup steps and remove checkmark emojis - Merge Xcode capabilities and Info.plist steps into single numbered items - Remove federated plugin system mention (now in CONTRIBUTING.md) - Remove debugging section (handled in Next Steps) README improvements: - Remove federated architecture section (detailed in CONTRIBUTING.md) - Focus on essential user information only Results in cleaner, more focused user documentation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
Basic Usage improvements: - Add note that callbackDispatcher must be a top-level function (runs in separate isolate) - Remove print statement from callback example - Add switch/case fallback for iOS task identifiers (Workmanager.iOSBackgroundTask) - Use kDebugMode instead of hardcoded true for isInDebugMode - Add required flutter/foundation.dart import - Replace UI code with simple task scheduling examples (no more StatelessWidget/Scaffold) Debugging documentation cleanup: - Simplify troubleshooting checklist (remove repetitive items covered elsewhere) - Condense from 16 checklist items down to 8 focused items - Add quickstart links to Common iOS Issues for easy double-checking: - Task identifier mismatches → Option B setup - Missing BGTaskSchedulerPermittedIdentifiers → iOS configuration - Background refresh disabled → Option A setup - Link to iOS setup guide in troubleshooting checklist Results in cleaner, more focused documentation with better cross-references. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Dramatically restructured project documentation with a comprehensive docs.page site and shortened the main README by 90%.
Key Changes
📝 Main README Transformation
📚 Comprehensive docs.page Structure
🎯 Documentation Highlights
Benefits
✅ 90% shorter README - easier to scan and get started quickly
✅ Usecase-driven approach - developers find solutions faster
✅ Better user experience - comprehensive docs with proper structure
✅ Platform specifics integrated - no more jumping between sections
✅ Professional documentation site - better than GitHub markdown
Structure Created
Testing
The docs.page site can be tested once this branch is deployed. The structure follows docs.page best practices with proper navigation, use case organization, and integrated platform specifics.
Migration Impact